Credits and Search tokens

The Cognism API meters usage with two quotas that are easy to confuse: search tokens count the records you retrieve, credits count the contact details you reveal. A third mechanism, rate limits, governs how fast you can send requests rather than how much data you receive.

The three quotas side by side

	Rate limits	Search tokens	Credits
Meters	Requests	Records returned	Contacts revealed
Window	60 seconds	Billing period	Billing period
Signalled by	`RateLimit-*` headers	`X-Rate-Results-*` headers	— (reported in the Cognism platform)
When exceeded	`429 rate_limit_exceeded`	`402 insufficient_budget`	—
Reduce by	Slowing down	Lowering `limit`, counting before searching	Requesting `contacts` only for the records you need

Search tokens

Search tokens are your result allowance. The API charges one token per record returned in the data array of a search response.


Unit	One record returned by `POST /persons/filter` or `POST /companies/filter`
Scope	Per account
Period	Your billing period. The balance resets at the account's next token reset.
Allotment	Set by your subscription
Not charged	Count endpoints, dictionaries, intent topics, settings, health

Reading your balance

Every search response reports where you stand:

Header	Meaning
`X-Rate-Results-Limit`	Your allotment for the current period
`X-Rate-Results-Limit-Remaining`	Records left in the current period
`X-Rate-Results-Limit-Reset`	Seconds until the period resets

The budget is checked before a search runs and charged after it returns, so a search is admitted whenever any balance remains: the last search of a period returns a full page and takes the balance to zero, and the next request is rejected.

When the budget runs out

HTTP/1.1 402 Payment Required
X-Rate-Results-Limit: 100000
X-Rate-Results-Limit-Remaining: 0
X-Rate-Results-Limit-Reset: 481200

{
  "error": "insufficient_budget",
  "message": "Your account has run out of search tokens. Retry after 481200 seconds.",
  "reason": "exhausted",
  "retryAfter": 481200
}

`reason`	Meaning	What to do
`exhausted`	The allotment for this period is used up.	Wait `retryAfter` seconds, or talk to your account team about a larger allowance. Do not retry in a loop — `retryAfter` can be days.
`stale_reset`	The billing period ended and the new one has not been provisioned yet.	Transient; `retryAfter` is `0`. Retry with exponential backoff.
`store_unavailable`	The budget could not be verified.	Transient. Retry with exponential backoff.

Spend tokens deliberately

Because tokens are charged per record, limit is a spend control as much as a page size. Requesting limit=100 when you render 20 rows spends five times the tokens you need. Two habits keep spend predictable:

Count first. Send the same filter to the count endpoint to learn how many records match before you decide whether to page through them.
Fetch what you display. Set limit to the number of records you will actually use on each page.

Credits

Credits meter contact data you reveal. Requesting the contacts segment on a person search (view=contacts) returns email addresses and phone numbers, and each person record returned with that segment is charged as one reveal against your credit balance.

POST /persons/filter?view=demographics,contacts&limit=25

Everything else costs no credits: searching without the contacts segment, counting, and the demographics, education, pastCompanies, skills and events segments. Company searches never consume credits.

💡
Search without contacts first, decide which people you need to reach, then request contacts for those records only — for example by filtering on their IDs. A person search with view=contacts and limit=100 can spend 100 credits in a single call.

Credit balance and consumption are reported in your Cognism account tooling rather than in API response headers.

Guidance for AI agents

An agent that spends on behalf of a user should estimate cost before it acts:

Search tokens spent = number of records returned. Use the count endpoint to know this in advance.
Credits spent = number of person records returned with the contacts segment. Confirm with the user before revealing contacts for more than a handful of records.

I found 340 matching people. Retrieving the first 50 will use 50 search tokens and no credits. Revealing emails and phone numbers for those 50 will use up to 50 credits. Continue?