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

# Rate Limits & Connection Limits

> How Codex counts requests against your plan's per-second rate limit, how many WebSocket connections you can open, and how to stay within both.

## Rate Limits

Each plan has a per-second rate limit on API requests:

| Plan | Rate Limit |
| - | - |
| **Almost free** | 5 requests/second |
| **Growth** | 300 requests/second |
| **Enterprise** | Custom — [contact our team](mailto:hello@codex.io) |

Requests that exceed your rate limit will be rejected. If you consistently hit your rate limit, consider [optimizing your usage](https://docs.codex.io/concepts/optimization.md) or upgrading your plan.

## Plan Allowances

Free accounts and new accounts are metered in [compute units](https://docs.codex.io/concepts/compute-units.md) (CU). Each request costs a set number of compute units, listed on [Compute Unit Costs](https://docs.codex.io/concepts/compute-unit-costs.md). Rate limits and connection limits are the same on compute-unit and request-based plans.

| Plan | Included | Rate limit |
| - | - | - |
| **Almost free** | 10,000 compute units over a rolling 30 days | 5 requests/second |
| **Growth** | The compute units in your plan each billing period (tiers on the [pricing page](https://www.codex.io/pricing)) | 300 requests/second |
| **Enterprise** | Custom | Custom |

On compute-unit plans, what happens past the allowance depends on [auto-scale](https://docs.codex.io/concepts/compute-units.md#auto-scale), and large overage can be [charged during the billing period](https://docs.codex.io/concepts/compute-units.md#overage-charges-during-the-billing-period).

To check your usage from code, call [`apiUsage`](https://docs.codex.io/concepts/compute-units#checking-usage-from-the-api). It returns usage, quota and percent used for the current period, on both kinds of plan.

Some older paid accounts are still on request-based plans, with a monthly number of requests.

On request-based plans:

| Plan | Requests included per month | Rate limit |
| - | - | - |
| **Growth** | From 1M (tiers on the [pricing page](https://www.codex.io/pricing)) | 300 requests/second |
| **Enterprise** | Custom | Custom |

The [request counting](#how-requests-are-counted) and [overage](#overages) rules below apply to request-based plans.

## Per-Request Limits

Going over most limits returns an error. Rows marked *dropped* silently return only the first N inputs, so split larger lists into batches.

| Query | Argument | Default | Max |
| - | - | - | - |
| [`getBars`](https://docs.codex.io/api-reference/queries/getbars), [`getTokenBars`](https://docs.codex.io/api-reference/queries/gettokenbars) | `datapoints` (`countback`, or the `from`/`to` range divided by `resolution`) | None | 1,500 (error above) |
| [`getTokenPrices`](https://docs.codex.io/api-reference/queries/gettokenprices) | `inputs` | None | 25 (extra inputs *dropped*) |
| [`tokens`](https://docs.codex.io/api-reference/queries/tokens) | `ids` | None | 100 |
| [`getDetailedPairsStats`](https://docs.codex.io/api-reference/queries/getdetailedpairsstats) | `input` | None | 10 (extra inputs *dropped*) |
| [`filterTokens`](https://docs.codex.io/api-reference/queries/filtertokens) | `limit` | 10 | 200 |
| [`filterTokens`](https://docs.codex.io/api-reference/queries/filtertokens) | `tokens`, `excludeTokens` | None | 200 each |
| [`filterPairs`](https://docs.codex.io/api-reference/queries/filterpairs), [`filterNetworks`](https://docs.codex.io/api-reference/queries/filternetworks), [`filterLaunchpads`](https://docs.codex.io/api-reference/queries/filterlaunchpads), [`categoryTokens`](https://docs.codex.io/api-reference/queries/categorytokens) | `limit` | | 200 |
| [`filterPredictionEvents`](https://docs.codex.io/api-reference/queries/filterpredictionevents), [`filterPredictionMarkets`](https://docs.codex.io/api-reference/queries/filterpredictionmarkets), [`filterPredictionTraders`](https://docs.codex.io/api-reference/queries/filterpredictiontraders), [`filterPredictionTraderMarkets`](https://docs.codex.io/api-reference/queries/filterpredictiontradermarkets) | `limit` | 100 | 200 |
| [`getTokenEvents`](https://docs.codex.io/api-reference/queries/gettokenevents), [`getTokenEventsForMaker`](https://docs.codex.io/api-reference/queries/gettokeneventsformaker) | `limit` | 10 | 200 |
| [`holders`](https://docs.codex.io/api-reference/queries/holders) | `limit` | 50 | 200 |
| [`balances`](https://docs.codex.io/api-reference/queries/balances) | `limit` | 200 | 200 |
| [`balances`](https://docs.codex.io/api-reference/queries/balances) | `tokens` | None | 200 |
| [`filterWallets`](https://docs.codex.io/api-reference/queries/filterwallets) | `limit` | 10 | 100 |
| [`filterWallets`](https://docs.codex.io/api-reference/queries/filterwallets) | `wallets` | None | 100 |
| [`filterTokenWallets`](https://docs.codex.io/api-reference/queries/filtertokenwallets) | `tokenIds` | None | 50 |
| [`listPairsForToken`](https://docs.codex.io/api-reference/queries/listpairsfortoken), [`listPairsWithMetadataForToken`](https://docs.codex.io/api-reference/queries/listpairswithmetadatafortoken) | `limit` | 10 | 250 (larger values return 250) |
| [`onPricesUpdated`](https://docs.codex.io/api-reference/subscriptions/onpricesupdated) | `input` | None | 25 |
| [`createApiTokens`](https://docs.codex.io/api-reference/mutations/createapitokens) | `count` | 1 | 25 |

## When You're Rate Limited

Requests over your limit are rejected with **HTTP 429** and an error coded `TOO_MANY_REQUESTS`:

```json theme={null}
{
  "errors": [
    {
      "message": "Your account has been rate limited, please upgrade your plan",
      "extensions": {
        "code": "TOO_MANY_REQUESTS",
        "retryAfterSeconds": 10
      }
    }
  ]
}
```

When we can tell exactly when your limit lifts, `extensions.retryAfterSeconds` says how many seconds to wait — and the same value is sent as the standard `Retry-After` header, so most HTTP client libraries will honor it without any code from you. A 429 without that field means your request budget is momentarily empty rather than your account being throttled; capacity typically returns within a second, so back off briefly on your own schedule.

> [!NOTE]
>
> Fixed retry intervals are the most common cause of prolonged rate limiting. If your interval is shorter than the penalty window, every retry lands inside it and extends the problem.

See [Errors & Retries](https://docs.codex.io/concepts/errors.md) for the full retry contract, including capacity errors that arrive as HTTP 200 and need the same backoff.

## How Requests Are Counted

Every interaction with the Codex API counts against your plan's monthly request limit. Usage is counted per query response, not per HTTP request. Here's how each type of interaction is measured:

| Interaction | What counts as 1 request |
| - | - |
| **Query** | Each query response (aliased queries in one request count separately) |
| **Subscription** | Each message the subscription sends you |
| **Webhook** | Each delivered message (when your condition is met). With `BATCH` publishing, each event in the batch counts as one request |

A few details to keep in mind:

* **Aliased queries each count separately.** If you combine multiple queries in one request using aliases, each query response is counted on its own, so `filterTokens` plus `getDetailedTokenStats` in one request counts as two.
* **Open subscriptions are free when idle.** Subscriptions count one request per delivered message. An open subscription with no messages flowing does not consume usage.
* **Webhooks count only on delivery.** A webhook counts only when a message is delivered, meaning when your condition is met. Codex's internal evaluation of events against your conditions is not counted.

> [!NOTE]
>
> Subscriptions can generate a high volume of requests depending on what you're subscribed to. For example, subscribing to trade events on a high-volume token could produce thousands of messages per hour — each one counts as a request.

## Overages

Overages are charged at the same per-million rate as your subscribed plan. For example, if you exceed your 1M Growth plan limit by 500K requests, you'll be charged for an additional 1M requests at the same per-million rate.

For high-volume usage (10M+ requests/month), contact us on [Discord](https://discord.com/invite/9ZB7zcWuBY) or [via email](mailto:support@codex.io) for custom plan pricing with volume discounts.

## WebSocket Connection Limits

WebSocket connections are the transport layer for [subscriptions](https://docs.codex.io/concepts/subscriptions.md). Each connection can carry multiple subscriptions.

| Plan | Connection Limit |
| - | - |
| **Growth** | 300 connections |
| **Enterprise** | Soft limit — contact our team for your specific needs |

Connection limits are per API key. Each connection can handle multiple subscriptions, so the connection limit is rarely a bottleneck.

## Capacity Per Connection

There is no hard limit on subscriptions per connection. What matters in practice is the **total number of tokens being watched on that connection** and how active those tokens are — not the count of `subscribe` messages. As a starting point, plan for **up to \~100 tokens watched per connection**. Spread tokens across connections rather than packing them onto one — if a single connection ends up carrying all your high-volume tokens (SOL, top trending tokens, busy pairs), it'll drop messages while your other connections sit idle. If you see drops, reduce the per-connection token count and add more connections.

The actual ceiling depends on:

* **Throughput** — subscribing to [`onTokenEventsCreated`](https://docs.codex.io/api-reference/subscriptions/ontokeneventscreated) for SOL generates far more messages than a low-volume token
* **Network capacity** — your internet connection and proximity to Western US affect throughput
* **Subscription type** — low-throughput streams like metadata updates can be packed considerably denser, while high-volume streams (launchpad events, busy chains) warrant dedicated connections

Note: `onPricesUpdated` accepts up to 25 tokens per `input` array — that's a hard cap on a single subscription request, not a recommended connection density. You can run multiple `onPricesUpdated` subscriptions on the same connection, just count their combined tokens against the per-connection budget.

## Latency Tips

For latency-sensitive clients:

* **Reuse connections.** Keep HTTP keep-alive on and send requests over a warm connection. Opening a new TLS connection for each request adds a handshake to every call.
* **Set timeouts with headroom.** Most requests return quickly, but a small share takes a few hundred milliseconds longer. A single quick retry handles these better than a very tight timeout.
* **Batch and cache.** Ask for many items in one call where the query allows it (for example up to 100 `ids` on [`tokens`](https://docs.codex.io/api-reference/queries/tokens)), and cache data that rarely changes, such as token logos.
* **Keep the `trace-id` header.** Every response carries a `trace-id` header. Send it to support with the UTC time if you see slow requests.

## Reducing Usage

For best practices on batching requests, caching, managing subscription lifecycle, and other ways to minimize your request count, see [Optimization](https://docs.codex.io/concepts/optimization.md).

> [!WARNING]
>
> Deactivating an API key does **not** automatically close active WebSocket connections. You must explicitly close your connections or they will continue to consume requests until they disconnect.


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