Rate limits

Three budgets apply to every account: 100 requests a minute, 2,500 batch items a minute, and 250,000 requests a UTC calendar month. Every authenticated response carries headers that say where you stand in each one.

The three budgets

Budget	Size	Counted on	What happens when it is spent
Requests	100 a minute, sliding window	Every authenticated request	`429 rate_limited` with a `Retry-After` header
Batch items	2,500 a minute	Each item in `POST /traders/batch` and `POST /markets/flow/batch` (or its deprecated alias `POST /markets/intel/batch`), including duplicate and invalid items	`429 rate_limited`, refused before any item runs
Monthly	250,000 a UTC calendar month	Requests that were admitted and answered	See the monthly quota below

The item budget works out to 100 requests times 25 items, so a full minute of 25-item batches fits inside it. The request budget is the one that stops you first, which means batching is never the more expensive choice. The item budget can still refuse at a window boundary, so handle a 429 from either.

The monthly quota

Pro includes 250,000 authenticated requests a UTC calendar month, whatever billing period you are on. What happens at request 250,001 depends on the pay as you go switch on Developers, which is off until you turn it on.

Pay as you go	Request 250,001 and after
On	The request answers as usual. Everything over 250,000 bills at $0.20 per 1,000 requests on a monthly invoice, up to 1,000,000 requests in the month. Past that ceiling you get `429 rate_limited` with `error.reason` `monthly_quota_exceeded`. Email support to have the ceiling raised.
Off	From October 1, 2026 the request answers `429 rate_limited` with `error.reason` `monthly_quota_exceeded` and a `Retry-After` that runs to the month’s reset.

A refused request is not counted against the month. Until October 1, 2026 the quota is counted and reported, and nothing is refused because of it. GET /api/v1/usage reports the same numbers under monthly_quota, and reading them spends nothing.

`monthly_quota` field	Meaning
`used`	Requests admitted so far this UTC calendar month.
`limit`	The 250,000 requests Pro includes in a month.
`remaining`	How many of the included requests are left.
`reset_at`	Unix seconds for the first instant of next month.
`enforced_from`	Unix seconds from which a request over `ceiling` is refused. That instant is October 1, 2026.
`binding`	`true` when a request over `ceiling` is refused right now. It is `false` before `enforced_from`.
`pay_as_you_go`	`true` when requests over `limit` keep answering and bill on a monthly invoice.
`ceiling`	The most requests the account is admitted in the month once enforcement starts. It equals `limit` with pay as you go off, and 1,000,000 with it on. It is `null` on an account with no ceiling at all.

Routes with their own rule

Route	Rule
`GET /api/v1/usage` and `GET /api/v1/me`	Neither spends the request budget. The two share a separate budget of 100 reads a minute per account.
`GET /api/v1/health`	Public, and limited to 120 requests a minute per IP address.
`GET /api/v1/stream`	Caps how many connections one key can hold open at once, and how many the cluster holds across all keys. One over either cap answers `429` with a `Retry-After`.
Public routes and refused credentials	Count against a per-IP budget of 1,200 requests a minute, shared by every caller behind that address. The `RateLimit-*` headers on a `401` or a `402` describe that budget, so a client looping on a bad key can still read how much of it is left. Over it, the `429` carries `error.reason` `ip_rate_limited`. An address in a cooldown carries `ip_throttled` and a `Retry-After` of minutes to days.

Headers on every response

RateLimit-Limit:           100
RateLimit-Remaining:       84
RateLimit-Reset:           42
X-RateLimit-Limit:         100
X-RateLimit-Remaining:     84
X-RateLimit-Reset:         1710772860
X-Monthly-Quota-Limit:     250000
X-Monthly-Quota-Remaining: 208770
X-Monthly-Quota-Reset:     1793491200
X-Request-Id:              req_550e8400

Header	Meaning
`RateLimit-Reset`	Seconds until the minute window resets.
`X-RateLimit-Reset`	The same instant, as a Unix timestamp.
`X-Monthly-Quota-Reset`	Unix timestamp of the first of next month, UTC.
`X-Request-Id`	Quote it in a support request. It is the same value as `meta.request_id` in the body, and it is on every response including `304`, `408`, and errors. A request header of the same name is ignored.

A batch response adds X-Request-Cost, the number of items this call charged, plus X-Batch-RateLimit-Limit, -Remaining, and -Reset for the item budget. Browser JavaScript can read every header above.

Handle a 429

HTTP/1.1 429 Too Many Requests
Retry-After: 12

{
  "object": "error",
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Retry after 12s.",
    "doc_url": "https://docs.0xinsider.com/api-reference/introduction#rate-limits",
    "retry_at": "2026-08-29T12:00:12Z"
  },
  "meta": { "request_id": "req_example", "cached": false, "cost": 1 }
}

Read Retry-After, in seconds. error.retry_at is the same instant, written as RFC 3339.
Sleep that long.
Send the request again. Cap the attempts so a long outage cannot loop forever: the code below stops after 5.

A 429 with error.reason monthly_quota_exceeded carries a Retry-After of days, not seconds. Do not put a worker to sleep on it. Turn on pay as you go, or wait for the month to reset. A 429 with error.reason ip_rate_limited is the per-IP budget, not your key’s. Every caller behind your address shares it, and the RateLimit-* headers describe that shared budget. One with ip_throttled is a cooldown of minutes to days after sustained over-limit traffic, so sleep all of Retry-After: an earlier request does not shorten it.

async function fetchWithBackoff(url, opts = {}, maxRetries = 5) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const res = await fetch(url, opts);
    if (res.status !== 429) return res;

    const wait = Number(res.headers.get("retry-after") ?? 1) * 1000;
    await new Promise(r => setTimeout(r, wait));
  }
  throw new Error("Rate limit retries exhausted");
}

const res = await fetchWithBackoff(
  "https://api.0xinsider.com/api/v1/whale-trades?limit=50",
  { headers: { Authorization: `Bearer ${process.env.OXINSIDER_API_KEY}` } }
);
const body = await res.json();

import os, time, requests

def get_with_backoff(url, params=None, max_retries=5):
    headers = {"Authorization": f"Bearer {os.environ['OXINSIDER_API_KEY']}"}
    for _ in range(max_retries):
        r = requests.get(url, params=params, headers=headers)
        if r.status_code != 429:
            return r
        time.sleep(int(r.headers.get("Retry-After", "1")))
    raise RuntimeError("Rate limit retries exhausted")

body = get_with_backoff(
    "https://api.0xinsider.com/api/v1/whale-trades",
    params={"limit": 50},
).json()

Use fewer requests

Ask for the largest limit the route allows. Most list routes cap it at 100 and default to 20, so one request can return five times as many rows.
Follow next_cursor to the next page instead of reading the first page again.
Look up known IDs in a batch. 25 wallets is one request.
Send If-None-Match on the 30 routes that return an ETag. A 304 is still one request, and it carries no body.
Run one poller per account, not one per process.

Routes that return an ETag

Group	Routes
Traders	Trader, Trader context (the JSON route, not `.md`), Trader P&L, Trader category records, Position timeline, Position timeline by trader, Positions, Large positions, Leaderboard, Trending wallets
Trades	Whale trades, Whale trade, Whale trades history, Counterparty executions, Counterparty makers
Markets	Explore markets, Sharp money flows, Smart money flows, Market flow, Market intel (deprecated), Market snapshot, Market holders, Market candles, Sports edge signals, Sports edge observations
Picks and flags	Pick of the Day, Pick of the Day archive, Pick of the Day ledger, Suspicious trades, Suspicious trade, Insider Radar, Insider Radar flag
System	Health

Reports, search, event replay, the stream, usage, account identity, exports, and every webhook route return no ETag.

What the budgets do not cover

The sandbox server. It has no credential, no plan, and no production data.
A request refused for its credential. It spends the per-IP budget, never yours.
A refused request. A 429 is not counted against the month.

Getting started

Integrations

Guides

Concepts

The three budgets

The monthly quota

Routes with their own rule

Headers on every response

Handle a 429

Use fewer requests

Routes that return an ETag

What the budgets do not cover

​The three budgets

​The monthly quota

​Routes with their own rule

​Headers on every response

​Handle a 429

​Use fewer requests

​Routes that return an ETag

​What the budgets do not cover

The three budgets

The monthly quota

Routes with their own rule

Headers on every response

Handle a 429

Use fewer requests

Routes that return an ETag

What the budgets do not cover