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
| Field | Type | Description |
|---|---|---|
discovery_searches.unlimited | boolean | true when no Trace allowance applies to the organization. The other fields are then null. |
discovery_searches.allowed | integer | null | Traces the organization may run in total. |
discovery_searches.used | integer | null | Traces counted against the allowance. |
discovery_searches.remaining | integer | null | Traces left, never below 0. At 0, POST /discovery/source returns 402 USAGE_LIMIT_REACHED. |
discovery_searches.purchase_adds | integer | null | Traces 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). |
screen | object | The 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_addsis 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; the402it 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
refreshand nocontinue_fromcan still return an existing cached result. Any other call returns402 USAGE_LIMIT_REACHED, withlimit: traceand the counts indata.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:readnordiscovery:write.
Required scope:
rate_limits:readordiscovery:write.