> ## Documentation Index
> Fetch the complete documentation index at: https://docs.0xinsider.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate limits

> Read your request allowances and handle rate limits without repeated polling.

Pro includes 500,000 requests per UTC calendar month, and Max includes 2,000,000. Both plans include 100 requests per minute and 2,500 batch items per minute. API keys and OAuth tokens on the same account share these allowances.

Read the response headers to see what remains. When a request returns `429`, check its reason and `Retry-After` before sending another request.

<span id="the-three-budgets" />

## Account allowances

| Allowance | What it counts | When exhausted |
| - | - | - |
| 100 requests per minute | Authenticated API requests, except the usage and identity reads below. The minute window is sliding. | `429 rate_limited` with `Retry-After`. |
| 2,500 batch items per minute | Every submitted item, including duplicates and invalid items, in trader and market-flow batches. | `429 rate_limited`; the batch is refused before its items run. |
| 500,000 requests per UTC month on Pro, or 2,000,000 on Max | Admitted requests. A refused request does not count. | The monthly quota rules below apply. |

A batch can contain up to 25 items, so 100 full batches fit both minute allowances. You still need to handle either limit, including near a window boundary.

<span id="the-monthly-quota" />

## Monthly quota and pay as you go

Enable pay as you go on [Developers](https://0xinsider.com/developers) if you need more than your plan's included requests. It is off by default.

| Setting | Behavior after the included allowance |
| - | - |
| Pay as you go off | From October 1, 2026 at 00:00 UTC, further requests return `429` with reason `monthly_quota_exceeded` until the next month. |
| Pay as you go on | Additional requests cost `$0.20` per 1,000 on a monthly invoice, up to 4 times the included allowance: 2,000,000 requests on Pro or 8,000,000 on Max. After that ceiling, requests return `429 monthly_quota_exceeded`. |

Read the account's returned `ceiling` instead of assuming a limit from its plan name. If `unavailable_reason` is `usage_price_reconciliation_required`, billing needs reconciliation before additional requests can be billed. Open [Billing](https://0xinsider.com/billing) or contact [support](mailto:support@0xinsider.com); repeated requests do not repair that setting.

A quota error's `Retry-After` and `error.retry_at` identify the next monthly reset. Repeated short retries cannot clear it; enable pay as you go, arrange a higher ceiling when needed, or schedule the next request for the reset.

## Check usage

[`GET /api/v1/usage`](/api-reference/endpoint/get-usage) returns `monthly_quota` without spending the normal request allowance:

| Field | Meaning |
| - | - |
| `used` | Admitted requests this UTC month. |
| `limit` | The included allowance: 500,000 on Pro or 2,000,000 on Max. |
| `remaining` | Included requests still available. |
| `reset_at` | The next month's start, as Unix seconds. |
| `enforced_from` | The enforcement start, as Unix seconds. |
| `binding` | Whether the ceiling applies now. |
| `pay_as_you_go` | Whether requests above the included quota can be billed. |
| `ceiling` | The account's admission ceiling: its included allowance when pay as you go is off, or up to 4 times that allowance when it is on. `null` means there is no ceiling. |
| `unavailable_reason` | `usage_price_reconciliation_required` when billing needs reconciliation. It is otherwise `null` or omitted. |

<span id="headers-on-every-response" />

## Response headers

These illustrative headers describe the request and monthly allowances:

```text theme={null}
RateLimit-Limit:           100
RateLimit-Remaining:       84
RateLimit-Reset:           42
X-RateLimit-Limit:         100
X-RateLimit-Remaining:     84
X-RateLimit-Reset:         1790841642
X-Monthly-Quota-Limit:     500000
X-Monthly-Quota-Remaining: 458770
X-Monthly-Quota-Reset:     1793491200
X-Request-Id:              req_example
```

| Header | Meaning |
| - | - |
| `RateLimit-Reset` | Seconds until the request window resets. |
| `X-RateLimit-Reset` | The reset instant, as Unix seconds. |
| `X-Monthly-Quota-Reset` | The next monthly reset, as Unix seconds. |
| `X-Request-Id` | The support reference for this request, also returned as `meta.request_id` when there is a JSON body. |

A batch adds `X-Request-Cost` for its item count and `X-Batch-RateLimit-Limit`, `X-Batch-RateLimit-Remaining`, and `X-Batch-RateLimit-Reset` for its item allowance. Browser JavaScript can read these headers.

`X-Request-Id` also appears on errors, timeouts, and `304` responses. Supplying your own header of the same name does not choose the response ID.

<span id="routes-with-their-own-rule" />

## Special limits

| Endpoint or caller | Rule |
| - | - |
| `/api/v1/usage` and `/api/v1/me` | They share a separate allowance of 100 reads per minute per account. |
| `/api/v1/health` | It is public and allows 120 requests per minute per IP. |
| `/api/v1/stream` | Limits apply to simultaneous connections per key and across the cluster. An excess connection returns `429` with `Retry-After`. |
| Public requests and rejected credentials | They use a shared per-IP allowance of 1,200 requests per minute. |

On a `401` or `402`, `RateLimit-*` describes the IP allowance, rather than the account's request allowance. An exhausted IP allowance produces reason `ip_rate_limited`; sustained excess traffic can produce `ip_throttled` with a longer cooldown.

## Handle a 429

| `error.reason` | Action |
| - | - |
| Omitted | Wait for `Retry-After`, then retry within your job's retry limit. |
| `ip_rate_limited` | Wait for the shared IP allowance to reset. |
| `ip_throttled` | Wait for the full cooldown, which can last minutes or days. |
| `monthly_quota_exceeded` | Change the quota setting or schedule a request after the monthly reset. |

This example makes at most 3 attempts and waits at most 60 seconds between attempts. Longer delays are returned to the caller for scheduling:

```javascript theme={null}
async function getWithBackoff(url) {
  for (let attempt = 0; attempt < 3; attempt++) {
    const response = await fetch(url, {
      headers: { Authorization: `Bearer ${process.env.OXINSIDER_API_KEY}` },
    });
    if (response.status !== 429 || attempt === 2) return response;

    const body = await response.clone().json();
    const seconds = Number(response.headers.get("retry-after"));
    if (body.error?.reason === "monthly_quota_exceeded"
        || !Number.isFinite(seconds) || seconds <= 0 || seconds > 60) {
      return response;
    }
    await new Promise(resolve => setTimeout(resolve, seconds * 1000));
  }
}

const response = await getWithBackoff(
  "https://api.0xinsider.com/api/v1/large-trades?limit=50"
);
const body = await response.json();
if (!response.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
```

<span id="use-fewer-requests" />

## Reduce repeated reads

* Use the largest supported page size and follow [pagination](/concepts/pagination).
* Batch up to 25 wallet or market lookups in one request.
* Share polling work across processes that use the same account.
* Reuse `ETag` values with `If-None-Match` where supported. A `304` saves the response body but still counts as 1 request.

<span id="routes-that-return-an-etag" />

## Endpoints with ETags

The current endpoints with `ETag` support are:

| Group | Endpoints |
| - | - |
| Traders | Trader, trader context JSON, trader P\&L, category records, both position timelines, positions, large positions, leaderboard, and trending wallets. |
| Trades | Large trades, single trade, history, counterparty executions, and counterparty makers, including whale-trade aliases. |
| Markets | Explore, sharp money flows and its alias, market flow and its intel alias, snapshot, holders, candles, pre-game sides, and pre-game observations. |
| Picks and flags | Pick of the Day, archive, ledger, suspicious trades and single flag, and Insider Radar aliases. |
| System | Health. |

<span id="what-the-budgets-do-not-cover" />

## Limits

Reports, search, event replay, streams, usage, account identity, exports, and webhooks do not return an `ETag`. The sandbox does not use an account quota and contains no production data.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.