Plan usage and funding

GET https://api.runinfra.ai/v1/usage

Read the workspace’s coding plan limits, credits after limits, and funding policy with a workspace API key. This endpoint is read-only. Use GET /v1/credits for the credit balance and budget, including when no coding plan exists.

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. If the limiter cannot be evaluated, 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"]
}

Field	Meaning
`workspace_id`	The workspace authenticated by the key.
`coding_plan.observed_at`	ISO 8601 observation time for the plan snapshot, or `null` when unavailable.
`coding_plan.availability`	Snapshot availability: `available`, `stale`, or `unavailable`. Read this before using retained data.
`coding_plan.current`	Plan state, or `null` when there is no current plan state.
`covers`	Covered operation categories. `chat` includes chat completions, Messages, and Responses. This list does not promise that a particular model is available.
`order`	Funding order. Credits require the owner’s choice and sufficient balance and cap; Standby covers chat only and must be available.

Current plan state

When coding_plan.current is present, it has these fields. All are required except resumes_at, serving_until, can_keep, remedy_code and billing_frozen; a required field can still be null where noted. This endpoint always returns them; they are optional only so that older cached snapshots still parse.

Field	Meaning
`tier`, `interval`	`starter`, `pro`, or `team`; interval is `month`.
`status`, `tile_state`, `serving`	Payment status, display state, and whether the plan can currently serve. A retained plan record does not by itself mean the plan is serving.
`price_cents`	The plan’s quoted monthly price, in US cents.
`cancel_at`, `renews_at`	ISO 8601 timestamps, or `null`. `renews_at` is set only while the plan is active and serving; it is `null` while payment is needed, canceling, paused, ended, or refund-closed.
`five_hour_limit_microcents`	The quoted 5-hour limit, including before its first window starts.
`plan_blocked_until`	Latest blocking plan reset as an ISO 8601 timestamp, counting pending commitments. `null` when no plan window blocks admission. Displayed window usage counts settled requests only.
`resumes_at`	Optional ISO 8601 timestamp for the earliest time requests can resume after a limit, considering plan resets, eligible Standby refills, and credits-period resets. Can be `null`.
`five_hour`	Window counters, or `null` before an admitted plan request starts the clock.
`week`	Weekly window counters.
`standby_day`	Daily Standby counters. Its `resets_at` is the refill time. Counters alone do not promise capacity or eligibility.
`included_month`	Plan usage counted in the billing period: `starts_at`, `resets_at`, and `used_microcents`. `null` when that period is unavailable.
`pending_change`	Scheduled tier change with `tier` and `effective_at`, or `null`.
`credits`	The credits-after-limits settings and counters described below.
`funding`	`null` on this policy read. It is not a receipt for a request.
`predicted_funding`	Availability for a nominal next covered chat request: `plan`, `credits`, `standby`, `refused`, or `null` when no prediction is available. The actual request can differ by key, cost, operation, or capacity.
`remedy_code`	Optional typed remedy behind `copy.remedy`: `enable_credits`, `raise_cap`, `add_funds`, `raise_key_limit`, `ask_owner`, `contact_support`, `wait_for_refill`, or `null`. Choose an action from this code rather than parsing display text. Null while `billing_frozen` is true.
`serving_until`	Optional. When the plan stops serving unless a payment succeeds: the payment grace deadline, or the scheduled cancellation when that is earlier. `null` while the plan is not serving.
`can_keep`	Optional. `true` while a scheduled cancellation can still be undone (Keep plan): `cancel_at` is in the future and the plan has no dispute hold or reversal fence and is not canceled, disputed, incomplete or refund-closed.
`billing_frozen`	Optional. `true` while an unpaid bill freezes the account and blocks requests until it is resolved in Billing. A negative credit balance is not a billing freeze. Plan and credits settings cannot lift it.
`copy`	Server-written display text. `summary` and `policy` describe the current policy; `actual` is `null` on this endpoint. `remedy` supplies the available next step when one exists.

Each window has starts_at, resets_at, used_microcents, limit_microcents, and used_percent. Body timestamps use ISO 8601. Percentages are integers clamped to 0 through 100. A request admitted before a limit can finish beyond it, so retain the exact counters when adding usage.

`credits` field	Meaning
`enabled`	Whether the owner chose credits after plan limits.
`cap_cents`	Cap per billing period, in US cents. With `enabled` true, `null` means no cap; with `enabled` false, credits are off.
`balance_cents`	Workspace credit balance in US cents; it can be negative.
`month_spent_microcents`	Calculated credit charges after plan limits during the billing period.
`pending_max_holds_microcents`	Maximum costs committed to requests still in flight against that cap.
`resets_at`	ISO 8601 billing-period end, or `null` when unavailable.

One cent is 1,000,000 microcents. One US dollar is 100,000,000 microcents. The credits cap after plan limits is separate from the workspace spend cap returned by /v1/credits.

Response funding headers

Model API responses carry these headers only when a coding plan decision applied to the request. They come from the admission snapshot. 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.

Header	Value
`x-runinfra-funding`	`plan`, `credits`, `standby`, or `refused`. Describes this request’s funding decision.
`x-runinfra-plan`	`starter`, `pro`, or `team`.
`x-runinfra-plan-5h-used-percent`	Integer percent used, clamped to 0 through 100. Omitted if no 5-hour window has started.
`x-runinfra-plan-5h-resets-at`	Unix timestamp in seconds. Omitted if no 5-hour window has started.
`x-runinfra-plan-week-used-percent`	Integer weekly percent used, clamped to 0 through 100.
`x-runinfra-plan-week-resets-at`	Unix timestamp in seconds.

These are response headers, not controls for selecting how a request is paid. They describe the request’s admission state, not the counters after it finishes. An idempotent replay retains the original funding receipt.

Calculated 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. This illustrative usage fragment shows a request with a list value of 294,000 microcents paid by the plan:

{
  "cost": 0,
  "runinfra": {
    "cost_microcents": 0,
    "plan_value_microcents": 294000,
    "paid_from": "plan"
  }
}

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. The calculated charge is not the final whole-cent credit debit for an individual request. Credit settlement carries fractional cents between requests, and the balance’s debt floor can limit a debit. See request cost and cached input for streaming and replay details.

Plan limit errors and Messages

When the plan is at a limit and neither credits nor Standby can serve the request, the OpenAI-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. See the complete error example. The Anthropic-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. The Messages success envelope reports token counts and does not expose usage.cost or usage.runinfra. Read its funding headers and use this endpoint for current plan state. See Anthropic Messages.

Start here

Guides

API reference

Pricing and credits

Help

Plan usage and funding

Request

Response

Current plan state

Response funding headers

Calculated cost and plan value

Plan limit errors and Messages

​Request

​Response

​Current plan state

​Response funding headers

​Calculated cost and plan value

​Plan limit errors and Messages

Request

Response

Current plan state

Response funding headers

Calculated cost and plan value

Plan limit errors and Messages