Credits

Every response to an API-key request under /data, /analytics and /reference carries an X-Credits-Used header: the number of credits that request consumed. Credits are the unit the API meters usage in, independent of any currency or plan — the same call costs the same number of credits whoever makes it, and re-pricing changes the schedule, not the header format.

Open beta: reported, not charged. During the observation window the header tells you what a call consumed so you can see and tune your integration’s usage. Nothing is deducted from an allowance and no request is rejected for consumption. Allowances and enforcement follow after the window closes; the header is how you get ready for them.

Reading the header

GET /data/transactions?limit=25
HTTP/1.1 200 OK
X-Credits-Used: 25

GET /data/companies/{id}
HTTP/1.1 200 OK
X-Credits-Used: 2

GET /analytics/aggregate/funding-rounds?…
HTTP/1.1 200 OK
X-Credits-Used: 5

GET /reference/filters/tag_id/values?q=fintech
HTTP/1.1 200 OK
X-Credits-Used: 0

GET /data/companies?limit=25&offset=999999
HTTP/1.1 400 Bad Request
X-Credits-Used: 0

The value is always a non-negative integer.

Value	Meaning
`N > 0`	This request consumed `N` credits
`0`	A free endpoint (search, filter values, lookups) or an error response — a failed call costs nothing
header absent	The endpoint is not metered, or the request was not authenticated with an API key

0 and absent are deliberately different: 0 means the API metered the call and found it free; absent means it was never metered.

What a call costs

Cost follows from what the call returns, not from which endpoint you hit:

Call	Credits
Funding rounds, valuations, news, notes, jobs — list, detail or sub-resource (`/data/transactions`, `/data/valuations`, `/data/news`, `/data/notes`, `/data/jobs`, `/data/companies/{id}/funding-rounds`, …)	1 per record
Map points (`/data/*/geo`)	1 per point
Every other `/data` collection — `entities`, `companies`, `investors`, `people`, `founders`, `universities`, `gov-ngo`, `funds` — as list, detail or sub-resource (`/data/companies`, `/data/investors/{id}/portfolio`, `/data/companies/{id}/team`, …)	2 per record
Aggregates, timeseries, funding analytics (`/analytics/*`)	5 per query, whatever it scans
Search, filter values, reference lookups (`/data/search`, `/reference/*`)	0

A GET /data/companies?limit=25 therefore reports 50 today: every company row is a full profile. A lighter summary shape priced at 1 per record is planned; when it ships, the header simply reports the lower number.

The prices are placeholders for the observation window and will be revised before anything is charged. Build against the header, not against the numbers on this page.

Which responses carry it

Carried: every response — success or error — to a request authenticated with an API key under /data/*, /analytics/* and /reference/*, including 403, 404, 429 and any 400 raised once authentication has completed.
Not carried: /platform/* self-service (account, API keys, usage, teams, lists), /system/*, /health, the API reference itself, the namespace indices (/data, /analytics, /reference), and any response rejected before authentication completes — a 401 for a missing or invalid token, or the 400 for an API-key request without its X-Client-Id header.

The header is listed in Access-Control-Expose-Headers, so browser-side code can read it:

const res = await fetch(`${baseUrl}/data/transactions?limit=25`, { headers });
const raw = res.headers.get("X-Credits-Used");
// null: not metered (or not an API-key request) — keep it distinct from a free call's 0
const credits = raw === null ? null : Number(raw);

Remaining balance

There is no X-Credits-Remaining header yet. The API only reports a figure it can compute exactly on every replica; a remaining balance needs the shared consumption counter that ships with enforcement. It will be added then, alongside the CREDITS_EXHAUSTED (402) error code, which is already reserved in the error catalog but is not returned by anything today.

Rate limits

How fast you can call the API — a separate control from how much you consume.

Errors

The error envelope and every stable error code, including the reserved 402.

Getting Started

Examples

Agents

Concepts

References

Reading the header

What a call costs

Which responses carry it

Remaining balance

Further reading

Rate limits

Errors

​Reading the header

​What a call costs

​Which responses carry it

​Remaining balance

​Further reading

Rate limits

Errors

Reading the header

What a call costs

Which responses carry it

Remaining balance

Further reading