Rate limits

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.

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.

Monthly quota and pay as you go

Enable pay as you go on 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 or contact support; 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 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.

Response headers

These illustrative headers describe the request and monthly allowances:

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.

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:

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}`);

Reduce repeated reads

Use the largest supported page size and follow 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.

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.

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.

Getting started

Integrations

Guides

Concepts

Account allowances

Monthly quota and pay as you go

Check usage

Response headers

Special limits

Handle a 429

Reduce repeated reads

Endpoints with ETags

Limits

​Account allowances

​Monthly quota and pay as you go

​Check usage

​Response headers

​Special limits

​Handle a 429

​Reduce repeated reads

​Endpoints with ETags

​Limits

Account allowances

Monthly quota and pay as you go

Check usage

Response headers

Special limits

Handle a 429

Reduce repeated reads

Endpoints with ETags

Limits