# Credits and limits

A company KPI lookup costs 1 × 2 = 2 credits.

## What a call costs

lookup 1 · history 2 · search 2 · evidence 5 · bulk 25 · change 1

Multiply by the dataset class. Charged after validation, before reading. CPI: 1 × 1 = 1 credit. [Price a call](https://api.gloom.sh/v1/datasets/cost?endpoint=awards.detail&id=1111111111111111111111111111111111111111) without a key.

## Headers

- `X-Credits-Cost`: spent; `X-Credits-Remaining`: balance; `X-Plan`: plan.
- `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`: this minute's credits.
- `Request-Id`: support reference. `Retry-After`: seconds to wait on 429 or 503.
- `ETag`: send it back as `If-None-Match`. An unchanged answer is a free `304`.

## Rate limits

- Per-minute budgets count credits: a 10-credit call uses 10. Exceeded: `429 rate_limited`.
- Period exhausted: `429 credits_exhausted` until renewal. `Retry-After` gives seconds. Unused credits expire.
- Errors cost nothing: a refused request is not charged, and a 404 or 503 after the charge is refunded. `X-Credits-Cost` shows what was kept.

## Your balance

`GET /v1/datasets/account` and `GET /v1/datasets/usage` are free. Routes that take `asOf` read a past point in time on every plan.

## Limits by plan

| Plan | Keys | Credits a month | Credits a minute |
| --- | --- | --- | --- |
| Basic | 5 | 150,000 | 300 |
| Desk | 20 | 1,000,000 | 1,200 |
| Enterprise | by contract | by contract | by contract |

Enterprise defaults: 100 keys, 6,000 credits/minute/key, until contracted.

No plan: 0 keys, 0 credits; `402 plan_required`.

## Cost by route

**All routes (112)**

| Route | Type | Class | Credits |
| --- | --- | --- | --- |
| `/v1/gpu/prices` | lookup | x4 | 4 |
| `/v1/gpu/history` | history | x4 | 8 |
| `/v1/gpu/changes` | change | x4 | 4 |
| `/v1/macro/cpi` | lookup | x1 | 1 |
| `/v1/energy/inventories` | lookup | x1 | 1 |
| `/v1/cftc/cot` | lookup | x1 | 1 |
| `/v1/cftc/cot/contracts/{contractCode}` | history | x1 | 2 |
| `/v1/awards` | search | x2 | 4 |
| `/v1/awards/{id}` | evidence | x2 | 10 |
| `/v1/kpis/{symbol}` | lookup | x2 | 2, 4 with `from` or `to` |
| `/v1/guidance/{symbol}` | lookup | x2 | 2, 4 with `from` or `to` |
| `/v1/credit/screen` | search | x4 | 8 |
| `/v1/credit/{symbol}` | history | x4 | 8 |
| `/v1/credit/{symbol}/instruments/{id}` | evidence | x4 | 20 |
| `/v1/exec-pay/{symbol}` | lookup | x2 | 2 |
| `/v1/exec-pay/{symbol}/{year}` | evidence | x2 | 10 |
| `/v1/risk-factors/{symbol}` | lookup | x2 | 2 |
| `/v1/risk-factors/{symbol}/{year}` | evidence | x2 | 10 |
| `/v1/events/{symbol}` | search | x1 | 2 |
| `/v1/revenue-breakdown/{symbol}` | history | x2 | 4 |
| `/v1/debt-maturities/{symbol}` | history | x2 | 4 |
| `/v1/catalysts` | search | x1 | 2 |
| `/v1/litigation/{symbol}` | search | x1 | 2 |
| `/v1/catalysts/events/{id}` | evidence | x1 | 5 |
| `/v1/catalysts/changes` | change | x1 | 1 |
| `/v1/sec/filings` | lookup | x1 | 1 |
| `/v1/sec/filing/documents` | lookup | x1 | 1 |
| `/v1/sec/filing/content` | evidence | x1 | 5 |
| `/v1/sec/insiders/{symbol}` | bulk | x1 | 25 |
| `/v1/sec/13f/{symbol}/holders` | history | x1 | 2 |
| `/v1/jobs` | search | x2 | 4 |
| `/v1/jobs/{symbol}` | history | x2 | 4 |
| `/v1/hiring/{symbol}/postings` | search | x2 | 4 |
| `/v1/hiring` | lookup | x2 | 2 |
| `/v1/hiring/{symbol}` | history | x2 | 4 |
| `/v1/jobs/coverage` | lookup | x2 | 2 |
| `/v1/hiring/coverage` | lookup | x2 | 2 |
| `/v1/apps/board` | history | x1 | 2 |
| `/v1/apps/app/{store}/{appId}` | history | x1 | 2 |
| `/v1/apps/company/{symbol}` | history | x1 | 2 |
| `/v1/apps/coverage` | lookup | x1 | 1 |
| `/v1/power/board` | bulk | x1 | 25 |
| `/v1/power/history` | history | x1 | 2 |
| `/v1/power/projects/{id}` | evidence | x1 | 5 |
| `/v1/power/coverage` | lookup | x1 | 1 |
| `/v1/perps/board` | lookup | x1 | 1 |
| `/v1/perps/history` | history | x1 | 2 |
| `/v1/perps/rankings` | lookup | x1 | 1 |
| `/v1/perps/compare` | lookup | x1 | 1 |
| `/v1/perps/market` | evidence | x1 | 5 |
| `/v1/perps/equity/{symbol}` | lookup | x1 | 1 |
| `/v1/attention` | lookup | x1 | 1 |
| `/v1/attention/{symbol}` | history | x1 | 2 |
| `/v1/supply-chain/{symbol}/graph` | bulk | x2 | 50 |
| `/v1/supply-chain/paths` | bulk | x2 | 50 |
| `/v1/supply-chain/{symbol}/counterparties` | search | x2 | 4 |
| `/v1/exposure/scenarios` | lookup | x2 | 2 |
| `/v1/exposure/analyze` | bulk | x2 | 50 |
| `/v1/transcripts` | search | x2 | 4 |
| `/v1/transcripts/{id}` | evidence | x2 | 10 |
| `/v1/document-search` | search | x2 | 4 |
| `/v1/document-search/documents/{docType}/{sourceId}` | evidence | x2 | 10 |
| `/v1/stories` | search | x2 | 4 |
| `/v1/stories/sources` | lookup | x2 | 2 |
| `/v1/stories/facets` | lookup | x2 | 2 |
| `/v1/stories/{id}` | evidence | x2 | 10 |
| `/v1/social-mentions/{symbol}/history` | history | x1 | 2 |
| `/v1/social-mentions/{symbol}/posts` | search | x1 | 2 |
| `/v1/short-volume/{symbol}` | history | x1 | 2 |
| `/v1/short-interest/{symbol}` | history | x1 | 2 |
| `/v1/sec/insider-signals` | bulk | x1 | 25 |
| `/v1/sec/13f/crowding` | bulk | x1 | 25 |
| `/v1/congress/trades` | search | x1 | 2 |
| `/v1/congress/members/{member}` | search | x1 | 2 |
| `/v1/congress/tickers/{symbol}` | search | x1 | 2 |
| `/v1/macro/curves` | lookup | x1 | 1 |
| `/v1/macro/curves/{curve}` | history | x1 | 2 |
| `/v1/macro/series/{seriesId}` | history | x1 | 2 |
| `/v1/macro/calendar` | lookup | x1 | 1 |
| `/v1/central-bank-rates` | history | x1 | 2 |
| `/v1/cds` | search | x2 | 4 |
| `/v1/cds/history` | history | x2 | 4 |
| `/v1/cds/indexes` | bulk | x2 | 50 |
| `/v1/cds/sovereigns` | bulk | x2 | 50 |
| `/v1/fundamentals/{symbol}/statements` | evidence | x4 | 20 |
| `/v1/fundamentals/{symbol}/statistics` | evidence | x4 | 20 |
| `/v1/fundamentals/{symbol}/profile` | evidence | x2 | 10 |
| `/v1/market/quotes` | search | x2 | 4 |
| `/v1/market/data` | evidence | x4 | 20 |
| `/v1/market/history` | history | x2 | 4 |
| `/v1/market/fields` | lookup | x2 | 2 |
| `/v1/futures/{root}/curve` | bulk | x2 | 50 |
| `/v1/futures/{root}/archive` | history | x2 | 4 |
| `/v1/futures/generics/{ticker}` | history | x2 | 4 |
| `/v1/rate-path` | bulk | x2 | 50 |
| `/v1/options/flow` | history | x2 | 4 |
| `/v1/options/{symbol}/iv` | history | x2 | 4 |
| `/v1/options/{symbol}/surface` | bulk | x2 | 50 |
| `/v1/options/{symbol}/chain` | bulk | x2 | 50 |
| `/v1/options/{symbol}/gamma` | bulk | x2 | 50 |
| `/v1/earnings/calendar` | search | x2 | 4 |
| `/v1/earnings/{symbol}/moves` | history | x2 | 4 |
| `/v1/ipo/calendar` | search | x2 | 4 |
| `/v1/mna/deals` | search | x2 | 4 |
| `/v1/mna/deals/{id}` | evidence | x2 | 10 |
| `/v1/equity-screener` | search | x2 | 4 |
| `/v1/crypto/markets` | bulk | x2 | 50 |
| `/v1/session-tape/movers` | bulk | x2 | 50 |
| `/v1/session-tape/highs-lows` | history | x2 | 4 |
| `/v1/session-tape/{symbol}/tape` | history | x2 | 4 |
| `/v1/analyst-estimates/{symbol}` | evidence | x2 | 10 |
| `/v1/analyst-estimates/{symbol}/revisions` | history | x2 | 4 |

- [Previous Authentication and keys](https://gloom.sh/datasets/docs/authentication)
- [Next Paging](https://gloom.sh/datasets/docs/paging)