# Credits & Rate Limits

## Credits

Credits are deducted from the account tied to your API key. Amounts and timing are listed under each endpoint and in **[Credit summary](/documents/credits-rate-limits.md#credit-summary)**. **`402 Payment Required`** indicates insufficient credits for that operation.

## Credit summary

Credit charges for **`/data`**, **`/metric`**, **`/screener`**, **`/ownership`**, and **`/events`** are as follows.

| Endpoint | Credits |
|----------|---------|
| `POST /data/filings` | **10** per successful debit. Debited **even if** the returned `filings` list is empty. |
| `POST /data/company` | **8** per successful debit. Debited **even if** `DATA_COMPANY_NOT_FOUND` is returned. |
| `GET /data/company/list` | **30** per page. |
| `POST /data/company/search` | **10** per call. A blank `query` returns no companies and is not charged. |
| `POST /data/line-items` | Sum over requested line items: tier **L0=10, L1=20, L2=30, L3=50** per line item. If your balance is less than the full sum, the rest of your balance is charged. |
| `POST /data/facts` | **ceil(n / 5) × 10** where **n** is the number of **deduplicated** fact ids. |
| `POST /data/statement` | **28** per debit, debited **even if** the filing is missing or nothing matches. role_label mode is tiered **28 / 48**: the extra **20** of the higher (48-credit) tier is capped at your remaining balance. |
| `POST /data/filing-statements` | **10** per successful debit. Debited **even if** the filing is missing. |
| `POST /data/income-statement` | **28** per successful debit. Debited **even if** the filing is missing or has no such statement. |
| `POST /data/comprehensive-income` | **28** per successful debit. Debited **even if** the filing is missing or has no such statement. |
| `POST /data/balance-sheet` | **28** per successful debit. Debited **even if** the filing is missing or has no such statement. |
| `POST /data/cash-flow-statement` | **28** per successful debit. Debited **even if** the filing is missing or has no such statement. |
| `POST /data/equity-statement` | **28** per successful debit. Debited **even if** the filing is missing or has no such statement. |
| `POST /data/facts/dimensional-breakdown` | **ceil((1 + N) / 5) × 10** where **N** is the number of the fact's direct dimensional children. **10 credits** are debited on `DATA_FACT_NOT_FOUND`. |
| `POST /data/line-items/dimensional-breakdown` | Tier credit for `line_item` (**L0=10 … L3=50**) + **ceil(N_total / 5) × 10** for returned slice facts. Partial billing applies. |
| `POST /data/compare/line-items` | For each line item, **(tier credits) × (number of filings compared)**. Rows listed in `failed_filings` are not charged. Same partial charging as **`POST /data/line-items`** when your balance is below the full price. |
| `POST /data/compare/facts` | **ceil(total_deduplicated_ids / 5) × 10** across the compared filing rows. Rows listed in `failed_filings` are not charged. |
| `POST /data/filings/excel` | **300**. Debited **even if** `DATA_EXCEL_OBJECT_NOT_IN_STORAGE` is returned. |
| `POST /metric/filings` | **10** |
| `POST /metric/all` | **158** |
| `POST /metric/all/filing-date` | **158** |
| `POST /metric/items` | **158** |
| `POST /metric/profitability` | **158** |
| `POST /metric/growth` | **158** |
| `POST /metric/financial-health` | **158** |
| `POST /metric/efficiency` | **158** |
| `POST /metric/cash-flow` | **158** |
| `POST /metric/valuation` | **158** |
| `POST /metric/valuation/filing-date` | **158** |
| `POST /metric/historical` | **55** base fee, plus **148 × (number of filing rows on the current page)**. Default page size is 3 filing rows. |
| `POST /screener/metrics` | Dynamic per request: **`max(65, 425 − tickerDiscount − lookbackDiscount − quarterlyDiscount + lookbackSurcharge + filterSurcharge + temporalSurcharge + includeSurcharge)`**. Range **89–1825**. See [Credit formula (`/screener/metrics`)](/documents/post-screenermetrics.md#credit-formula-screenermetrics) for the formula. Debited **even if** results are empty. |
| `GET /screener/metrics/filters` | **0**. |
| `POST /ownership/transactions` | **30** per page. Debited **even if** `OWNERSHIP_COMPANY_NOT_FOUND` is returned. |
| `POST /ownership/stats` | **40** base + **ceil(n / 1000) × 5**, where **n** is the number of participating transactions. The base is debited **even if** `OWNERSHIP_COMPANY_NOT_FOUND` is returned. |
| `POST /ownership/transaction-ids` | **ceil(n / 5) × 10** where **n** is the number of **deduplicated** ids (max 100). |
| `POST /screener/ownership` | Dynamic per request: **`max(65, 200 − tickerDiscount − shortWindowDiscount + fullHistorySurcharge + 40 × conditions)`**. Range **65–920**. See [Credit formula (`/screener/ownership`)](/documents/post-screenerownership.md#credit-formula-screenerownership) for the formula. Debited **even if** results are empty. |
| `GET /ownership/tickers` | **30** per page. |
| `POST /ownership/names` | **30** per successful debit. Debited **even if** `OWNERSHIP_COMPANY_NOT_FOUND` is returned. |
| `GET /ownership/transaction-types` | **0** — static catalog, no charge. |
| `POST /ownership/initial-holdings` | **30** per page. Debited **even if** `OWNERSHIP_COMPANY_NOT_FOUND` is returned. |
| `POST /ownership/initial-holdings/stats` | **40** base + **ceil(n / 1000) × 5**, where **n** is the number of participating holdings. The base is debited **even if** `OWNERSHIP_COMPANY_NOT_FOUND` is returned. |
| `POST /ownership/initial-holding-ids` | **ceil(n / 5) × 10** where **n** is the number of **deduplicated** ids (max 100). |
| `POST /screener/initial-holdings` | Dynamic per request, same formula as `POST /screener/ownership` ([Credit formula (`/screener/ownership`)](/documents/post-screenerownership.md#credit-formula-screenerownership)). Range **65–920**. Debited **even if** results are empty. |
| `POST /ownership/institutional-holdings/manager-history` | **30** per successful debit. Debited **even if** `OWNERSHIP_MANAGER_NOT_FOUND` is returned. |
| `POST /ownership/institutional-holdings/portfolio` | **30** per page. Debited **even if** the manager or the quarter is not found. |
| `POST /ownership/institutional-holdings/security` | **30** per page (flat mode); **40** flat with `group_by_quarter=true`. Debited **even if** `OWNERSHIP_SECURITY_NOT_FOUND` is returned. |
| `POST /ownership/institutional-holdings/managers` | **10** per call. A blank `query` returns no managers and is not charged. |
| `POST /screener/institutional-holdings` | Dynamic per request: **`max(65, 200 + 40 × conditions − narrowWindowDiscount + noWindowSurcharge)`**. Range **160–720**. See [Credit formula (`/screener/institutional-holdings`)](/documents/post-screenerinstitutional-holdings.md#credit-formula-screenerinstitutional-holdings) for the formula. Debited **even if** results are empty. |
| `GET /events/types` | **0**; Starter or higher required. |
| `POST /events/filings` | **10** per page, including empty results and missing companies. |
| `POST /events/filing` | **30**, with or without selected Items or original text; post-charge resource errors remain charged. |
| `POST /screener/events` | **65–280** per page; see [Credit formula (`/screener/events`)](/documents/post-screenerevents.md#credit-formula-screenerevents). |
| `GET /billing/balance` | **0** — free balance check. Returns `{"credits_balance": <int>}` for the API key's account. Rate-limited at 30/minute. |

**Metrics resolution tiers (for `/data/line-items` and `/data/compare/line-items`):** each requested label is classified into **L0–L3**, which sets that line item’s credit cost. The chosen tier is echoed on each result as **`_resolution_level`** (`"L0"` through `"L3"`). The response carries **`_correction`** when a name was matched by filing label or at L3, matched several concepts, or could not be resolved.

## Workflow budgets

Indicative credit ranges for common workflows, so you can size a plan before you start. Numbers assume the L1 tier on common line-item names (`revenue`, `net income`, `operating income`, etc.). Rarer or ambiguous names land at L2–L3 and cost more; see the tier list in [Credit summary](/documents/credits-rate-limits.md#credit-summary).

| Workflow | Endpoint pattern | Typical credits |
|---|---|---|
| Discover one company (identity + coverage map) | `POST /data/company` | **8** |
| List all filings for one company-year | `POST /data/filings` | **10** |
| Pull all three primary statements (income / balance / cash flow) for one filing | `POST /data/income-statement` + `/balance-sheet` + `/cash-flow-statement` | **84** (28 × 3) |
| Pull a few specific line items from one filing (3 items × L1) | `POST /data/line-items` | **60** (3 × 20) |
| Five-year trend on one metric for one company | `POST /data/line-items` × 5 filings, 1 item, L1 | **100** (5 × 20) |
| Peer comparison: 5 companies × 1 metric × 1 year (L1) | `POST /data/compare/line-items` | **100** (1 × 20 × 5) |
| All key metrics snapshot for one company (1 call) | `POST /metric/all` | **158** |
| Full dimensional breakdown of revenue for one filing (~50 slice facts) | `POST /data/line-items/dimensional-breakdown` | **~120** (20 + 100) |
| Download one filing's Excel workbook | `POST /data/filings/excel` | **300** |

Reference: a **Starter** plan (20,000 credits / month) covers about **330** three-item line-item queries, **240** three-statement pulls, or **126** `/metric/all` snapshots per month — pick the mix that fits your workflow.

## Rate limiting

When limits are exceeded, the API returns **`429 Too Many Requests`** with `detail.error_code` **`RATE_LIMIT_EXCEEDED`**. Limits apply per account across all API keys on that account.

## Rate limits

Per-account limits (requests per minute, per route):

| Method | Path | Limit |
|--------|------|-------|
| POST | `/data/filings` | 120 |
| POST | `/data/company` | 120 |
| GET | `/data/company/list` | 120 |
| POST | `/data/company/search` | 120 |
| POST | `/data/line-items` | 100 |
| POST | `/data/facts` | 100 |
| POST | `/data/statement` | 120 |
| POST | `/data/filing-statements` | 120 |
| POST | `/data/income-statement` | 120 |
| POST | `/data/comprehensive-income` | 120 |
| POST | `/data/balance-sheet` | 120 |
| POST | `/data/cash-flow-statement` | 120 |
| POST | `/data/equity-statement` | 120 |
| POST | `/data/facts/dimensional-breakdown` | 60 |
| POST | `/data/line-items/dimensional-breakdown` | 60 |
| POST | `/data/compare/line-items` | 60 |
| POST | `/data/compare/facts` | 60 |
| POST | `/data/filings/excel` | 20 |
| POST | `/metric/filings` | 100 |
| POST | `/metric/all` | 60 |
| POST | `/metric/all/filing-date` | 60 |
| POST | `/metric/items` | 60 |
| POST | `/metric/profitability` | 60 |
| POST | `/metric/growth` | 60 |
| POST | `/metric/financial-health` | 60 |
| POST | `/metric/efficiency` | 60 |
| POST | `/metric/cash-flow` | 60 |
| POST | `/metric/valuation` | 60 |
| POST | `/metric/valuation/filing-date` | 60 |
| POST | `/metric/historical` | 60 |
| POST | `/screener/metrics` | 10 |
| GET | `/screener/metrics/filters` | 60 |
| POST | `/screener/ownership` | 10 |
| POST | `/ownership/transactions` | 120 |
| POST | `/ownership/stats` | 120 |
| POST | `/ownership/transaction-ids` | 120 |
| GET | `/ownership/tickers` | 120 |
| POST | `/ownership/names` | 120 |
| GET | `/ownership/transaction-types` | 60 |
| POST | `/ownership/initial-holdings` | 120 |
| POST | `/ownership/initial-holdings/stats` | 120 |
| POST | `/ownership/initial-holding-ids` | 120 |
| POST | `/screener/initial-holdings` | 10 |
| POST | `/ownership/institutional-holdings/manager-history` | 120 |
| POST | `/ownership/institutional-holdings/portfolio` | 120 |
| POST | `/ownership/institutional-holdings/security` | 120 |
| POST | `/ownership/institutional-holdings/managers` | 120 |
| POST | `/screener/institutional-holdings` | 10 |
| GET | `/events/types` | 60 |
| POST | `/events/filings` | 120 |
| POST | `/events/filing` | 60 |
| POST | `/screener/events` | 10 |
| GET | `/billing/balance` | 30 |