Plan usage and funding

Request

curl https://api.runinfra.ai/v1/usage \
  -H "Authorization: Bearer $RUNINFRA_GATEWAY_KEY"

A legacy key scoped to a deployment or endpoint cannot read workspace finances. These keys, and internal canary keys, receive 403 usage_scope_violation. Use a workspace key.

The endpoint has a separate limit of 60 reads per minute per key, in addition to the normal per-key request limit. Responses carry Cache-Control: no-store. A rate refusal returns 429 rate_limit_exceeded; follow its retry headers. During a rate-limit store outage, both limits are counted per server. If the rate-limit store is not configured or the connection gate cannot evaluate the request, the response is 503 limiter_unavailable.

Response

This example shows a workspace without a coding plan. The identifier and observation time are illustrative.

{
  "workspace_id": "00000000-0000-4000-8000-000000000001",
  "coding_plan": {
    "observed_at": "2026-09-23T12:00:00.000Z",
    "availability": "available",
    "current": null
  },
  "covers": ["chat", "embeddings", "rerank"],
  "order": ["plan", "credits", "standby", "refused"]
}

Response funding headers

Only when a coding plan decision applies, x-runinfra-funding identifies the request's admission snapshot. It is a response header, not a control for selecting how a request is paid. Its values are plan, credits, standby, or refused. An idempotent replay retains the original funding receipt. Existing holders of retired plans are served until their own paid period ends, subject to payment and eligibility conditions.

These response headers are sent only to workspaces that hold a plan. All of these response headers describe the request's admission state, not the counters after it finishes.

A workspace without a plan receives none of them. Uncovered operations, Credits only keys, non-serving plans, and promotional zero-price requests use the ordinary pay-as-you-go path without plan headers.

Calculated request cost and plan value

On chat completions and Responses, usage.cost reports the calculated charge in US dollars. It is 0 when the plan or Standby paid. usage.runinfra.cost_microcents is the same calculated charge in integer microcents.

usage.runinfra.plan_value_microcents is the usage value counted at the applicable per-token rates. usage.runinfra.paid_from is plan or standby. Both fields are added only when the plan or Standby paid. A credit-funded response retains the ordinary cost fields; use x-runinfra-funding when present to identify credits after plan limits.

For example, a request with an illustrative list value of 294,000 microcents paid by the plan reports that value separately while its calculated charge is zero.

Your balance is debited in whole cents, and the fraction of a cent left over carries to your next request, so one debit can differ from one request's cost by less than a cent. Over any period the two agree to within one cent of carry, unless the balance has reached its debt floor, which can limit a debit.

See request cost and cached input for streaming and replay details.

Plan limit errors and Messages

When only running requests hold the rest of a limit, the request waits on the server for up to 30 seconds and then gets a retryable 429 plan_window_busy. Messages and Responses keep it as a 429 rate_limit_error. When the plan is at a limit and neither credits nor Standby can serve the request, the chat-compatible envelope returns 402 plan_limit_reached. Its fields include the blocking window, reset time, standby_blocker, credit blocker, and a next step. It carries x-should-retry: false and no Retry-After. Read the fields returned with the refusal; see the complete plan-limit error reference.

The Messages-compatible /v1/messages error envelope keeps error.type: "billing_error" and the message text, plus request_id. It does not preserve error.code, window fields, standby_blocker, or fixes. The message therefore states the product, blocking limit, reset time, Standby condition, and next step with its Billing URL.

On plan and Standby responses, the Messages success envelope adds usage.cost (0) and usage.runinfra, including cost_microcents and paid_from, to its token counts, in the JSON body and in the stream's final message_delta. Credit-funded and pay-as-you-go Messages responses report token counts only. Read the funding headers for which source paid, and use this endpoint for current plan state. See Messages.