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 shows where the compute units went.

This page applies to accounts on compute-unit plans. If your account is billed by request count, Rate Limits & Connection Limits describes how your usage is measured. Your billing page 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, 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 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.
• Mutations are priced the same way and are shown as their own category on the usage page.

​

Errors are free, except NOT_FOUND

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.

One error is charged: NOT_FOUND. The lookup ran and found nothing, so the root field is billed and counted as a request like any other answer.

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)
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 covers subscription lifecycle management.

​

Webhooks

Component	Cost
Each successful delivery to your endpoint	2 CU
Each event checked against a webhook’s conditions	Free
Each failed delivery attempt	Free

Only deliveries your endpoint accepts are billed, the same as on request-billed plans.

Creating and deleting webhooks are mutations and carry the mutation base cost listed on Compute Unit Costs.

​

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

Plans and prices are on the pricing page 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. Large overage can be charged during the period (see Overage charges during the billing period); the rest 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). 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.

​

Overage charges during the billing period

On self-serve plans with auto-scale on, you do not wait until the end of the period to pay for large overage. Each time your overage in a period grows by another 1 million compute units, we can charge your payment method for all of the overage so far in that period, less what we already charged in that period. Plans by agreement are invoiced as agreed.

• Each charge is a separate invoice, charged to the payment method on your subscription. The billing page shows the total charged so far this period.
• When a charge is paid, the same amount is credited on your next subscription invoice, so you never pay twice for the same overage. The total that you pay for a period does not change.
• If a charge fails, or your bank asks you to approve it and you do not, every API key on the account is paused at once. Pay the invoice from the billing page (Pay invoice) to restore access; see Errors & Retries.
• If you upgrade during the period, the credit applies to the upgrade invoice.

​

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 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 Usage from the API

The apiUsage query returns your account’s usage for the current period against your allowance. It is free, and it still works when the account is over its limit, so you can call it from your own monitoring.

query {
  apiUsage {
    unit
    used
    limit
    remaining
    percentUsed
    periodStart
    periodEnd
    updatedAt
    breakdown {
      query
      mutation
      subscription
      webhook
    }
  }
}

• unit is COMPUTE_UNITS on compute-unit plans and REQUESTS on request-based plans. used, limit, remaining and breakdown are in that unit, returned as strings.
• limit, remaining and percentUsed are null when the plan has no quota. percentUsed can go above 100 when auto-scale is on.
• The numbers are refreshed by the usage pipeline, not on every request. updatedAt says when they were last refreshed.

​

Estimating Usage in the Explorer

The explorer shows what your queries will cost before you build them into your app:

• CU meter shows each query’s compute-unit cost under the response, with the equivalent number of requests. Add queries and streams to a monthly estimate, and it is matched against the self-serve plans.
• Stream meter counts messages while a subscription runs and projects them per hour and per 30 days, in compute units and in requests.

​

Checking the Cost of a Request

Add the usageData field to any query to see what that request cost. The field itself is free.

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.