Plan usage and funding

Read coding plan windows and policy, identify what paid for a request, and handle a plan limit.

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. 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"]
}

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, the plan has no dispute hold or reversal fence, its subscription has had no payment dispute (a bank inquiry does not count), and it is not canceled, disputed, incomplete or refund-closed. After a payment dispute, can_keep stays false, even once the hold is released.
billing_frozen	Optional. true while an unpaid bill or a payment dispute freezes the account and blocks requests. Resolve an unpaid bill in Billing. For a payment dispute, contact support. 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 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 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.

On plan and Standby responses, the Messages success envelope adds usage.cost (0) and usage.runinfra (cost_microcents, plan_value_microcents, 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 Anthropic Messages.