> ## 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.

# Compute Units

> How compute-unit plans meter API usage: what a compute unit is, how each request is priced, plan allowances, auto-scale, and the usageData field

Compute-unit plans meter what each request actually does instead of counting requests. Every operation has a base cost in compute units (CU), an account has an allowance of compute units for its period, and the [usage page](https://dashboard.codex.io/dashboard/usage?utm_source=codex\&utm_medium=docs\&utm_campaign=concepts-compute-units) shows where the compute units went.

> [!NOTE]
>
> This page applies to accounts on compute-unit plans. If your account is billed by request count, [Rate Limits & Connection Limits](/concepts/rate-limits#how-requests-are-counted) describes how your usage is measured. Your [billing page](https://dashboard.codex.io/dashboard/billing?utm_source=codex\&utm_medium=docs\&utm_campaign=concepts-compute-units) shows which applies to you.

## What a Compute Unit Is

A compute unit is the unit every Codex operation is priced in. A typical query costs a few compute units, a subscription message costs one, and lightweight operations cost a fraction of one, so costs are shown with up to six decimal places. The base cost of every documented operation is listed on [Compute Unit Costs](/concepts/compute-unit-costs), and your billing page shows the same table with any custom prices your account has.

Rate limits are separate from compute units and do not change with the size of your plan: free accounts get 5 requests per second and paid plans get 300 requests per second, the same as request-based plans. See [Rate Limits & Connection Limits](/concepts/rate-limits) for the connection limits.

## How a Request Is Priced

Pricing is flat and deterministic: two identical requests cost the same number of compute units. Response size and processing time are measured and reported, but they do not change the price of a query or a mutation.

### Queries and mutations

* **Each root field is billed its base cost every time it is called.** A request that sends `filterTokens` and `getDetailedTokenStats` together costs the same as sending them separately. Aliased root fields are each billed.
* **Some response types add a per-object cost.** For example, every token returned by `filterTokens` adds the per-object cost of the token type, so asking for 50 tokens costs more than asking for 10. A few nested fields carry their own cost each time they are resolved. Both are listed under [Response types and fields](/concepts/compute-unit-costs#response-types-and-fields).
* **Mutations are priced the same way** and are shown as their own category on the usage page.

### Errors are free

A root field whose response carries a GraphQL error is not charged and does not count as a request. Root fields in the same request that succeeded are billed as if they had been sent alone, so a partial response only bills the fields that returned data. A request that fails before execution (a parse or validation error) costs nothing.

Introspection queries are free. They cannot be combined with data fields in the same request; the API rejects the request with `Cannot mix introspection queries with data queries in the same request. Please send introspection and data queries separately.`

### Subscriptions

A subscription is billed for what it delivers and for how long it stays open:

| Component | Cost |
| - | - |
| Each message delivered | The subscription's base cost (most are 1 CU per message; see [Compute Unit Costs](/concepts/compute-unit-costs#subscriptions)) |
| Message payload | 1 CU per MB of payload delivered |
| Open time | 0.25 CU per minute for each open subscription, billed when the subscription ends or its connection closes |

An idle subscription still accrues the open-time cost, so close subscriptions you no longer need. [Optimization](/concepts/optimization#manage-subscription-lifecycle) covers subscription lifecycle management.

### Webhooks

| Component | Cost |
| - | - |
| Each event processed against a webhook's conditions | 0.01 CU (0.05 CU for raw transaction webhooks) |
| Each delivery attempt to your endpoint | 2 CU, whether or not your endpoint accepted it |

Creating and deleting webhooks are mutations and carry the mutation base cost listed on [Compute Unit Costs](/concepts/compute-unit-costs#mutations).

## Allowances and Billing Periods

Every account has an allowance of compute units for its period:

| Account | Allowance | Period |
| - | - | - |
| **Free** | 10,000 compute units | A rolling 30-day window that starts at signup (or at the downgrade from a paid plan) |
| **Paid** | The compute units included in your plan: 3, 5, 10, 25 or 50 million per month | Your subscription's billing period |
| **Enterprise** | Custom | Custom — [contact our team](mailto:hello@codex.io) |

Plans and prices are on the [pricing page](https://www.codex.io/pricing) and in the dashboard. Usage inside the allowance is included in the plan price.

You receive an email when your usage crosses 50% and 80% of the allowance, and again at 100%. What happens at 100% depends on auto-scale.

## Auto-Scale

Auto-scale is a setting on paid plans, under **Settings → Billing Settings** in the dashboard. It decides what happens when you use your whole allowance before the period ends:

* **Auto-scale on** — requests keep working. Usage beyond the allowance is billed as overage at your plan's overage rate per 1 million compute units, shown on your billing page, and appears on the invoice for that period. You receive a further email at 150% of the allowance.
* **Auto-scale off** — usage stops at the allowance. When usage reaches 100%, every API key on the account is paused until the period rolls over or you change plan, and requests are rejected with HTTP 403 (see [Errors & Retries](/concepts/errors#forbidden-403)). Nothing beyond the allowance is billed. Enforcement runs asynchronously, so usage can briefly overshoot the allowance; the overshoot is not billed.

Free accounts cannot enable auto-scale, so they pause at 100% of the allowance.

An API key with its own custom compute-unit limit is paused on its own when it reaches 100% of that limit, whatever the auto-scale setting.

## Unpaid Invoices

If an invoice cannot be collected, every API key on the account is paused and requests are rejected with HTTP 403 until the invoice is paid. Pay it from the billing portal (**Pay invoice** on the billing page); access is restored by the successful payment and by nothing else, so a new billing period does not lift the pause.

## The Usage Page

The [usage page](https://dashboard.codex.io/dashboard/usage?utm_source=codex\&utm_medium=docs\&utm_campaign=concepts-compute-units) shows your compute units for the current period and for any range you pick:

* A usage card with the compute units used against the allowance and the percentage used.
* Charts of compute units over time.
* Breakdowns by **query**, **mutation**, **subscription**, and **webhook**, ranking each operation (or webhook type) by the compute units it consumed and its share of the selected usage.

Paid plans also see a **This period so far** estimate on the billing page: allowance used, overage, and the estimated overage charge. It is an estimate; your invoice is the source of truth.

## Checking the Cost of a Request

Add the [`usageData`](/api-reference/queries/usagedata) field to any query to see what that request cost. The field itself is free.

```graphql theme={null}
query {
  filterTokens(filters: { network: [1] }, limit: 50) {
    results {
      token {
        address
        name
      }
    }
  }
  usageData {
    total {
      computeUnits
      count
    }
    items {
      resource
      entityType
      metrics {
        computeUnits
        count
      }
    }
  }
}
```

* `total.computeUnits` is the compute units charged for the request that carried the field.
* `items` lists each priced component: `resource` is the operation or field (for example `filterTokens`), and `entityType` is set for per-object costs (for example the token type returned by `filterTokens`).
* `count` is the number of billable units, not requests: 1 for a field that was called once, or the number of objects for a per-object cost. `bytes` and `durationMs` are measured for reference and do not affect the price under standard pricing.
* All values are returned as strings.

When the whole request was free (for example, every root field returned an error), `usageData` reports zeros.


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