Get Allowances

Show how many discovery Traces and Risk Screening runs your organization has left. Read it before a POST /discovery/source call or a screening upload to know whether it can run. Both are lifetime allowances: they do not reset.

A Trace is one accepted POST /discovery/source call: a one-tier or direct-operated search, a traversal, or a continuation. It counts once, whatever its max_sweeps. The field is named discovery_searches, and it counts Traces.

Request

GET /rate-limits/allowances. No parameters.

Response

FieldTypeDescription
discovery_searches.unlimitedbooleantrue when no Trace allowance applies to the organization. The other fields are then null.
discovery_searches.allowedinteger | nullTraces the organization may run in total.
discovery_searches.usedinteger | nullTraces counted against the allowance.
discovery_searches.remaininginteger | nullTraces left, never below 0. At 0, POST /discovery/source returns 402 USAGE_LIMIT_REACHED.
discovery_searches.purchase_addsinteger | nullTraces one more paid checkout would add to allowed. 0 when a purchase would not raise it, or when your key cannot check out (an organization key that is not self-serve).
screenobjectThe Risk Screening runs of the calling organization, with the same fields. At remaining 0, a screening upload returns 402 USAGE_LIMIT_REACHED.

How the allowance works

  • The allowance. An organization gets 10 Traces, and 30 once it has paid for a checkout. Epoch can grant more, or set the organization's allowance itself. purchase_adds is 20 until the first paid checkout, and 0 after it or once Epoch has set the allowance. It is also 0 for an organization key that is not self-serve, which cannot check out; the 402 it gets points to support instead.
  • One allowance per organization family. A parent organization and its child organizations share one allowance. A child organization's key, or a call with x-acting-as, reports that shared allowance.
  • What counts. A running Trace counts in used. It stops counting when it settles as a cached, failed or unspent run.
  • When none is left. A repeat with no refresh and no continue_from can still return an existing cached result. Any other call returns 402 USAGE_LIMIT_REACHED, with limit: trace and the counts in data.details (see Limit refusals in the error codes).

The limits that reset (calls an hour, the daily trace-sweep limit, Risk Screening runs a day) are reported on GET /rate-limits. A call over one of them returns 429, with the limit and its reset in data.details.

Errors

  • 401 โ€” missing or invalid key.
  • 403 โ€” the key has neither rate_limits:read nor discovery:write.

Required scope: rate_limits:read or discovery:write.