> ## Documentation Index
> Fetch the complete documentation index at: https://runinfra.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Plan usage and funding

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

```http theme={"dark"}
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](/docs/api-reference/credits) for the credit balance and budget, including when no coding plan exists.

## Request

```bash theme={"dark"}
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.

```json theme={"dark"}
{
  "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:

```json theme={"dark"}
{
  "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](/docs/api-reference/chat-completions#the-cost-of-the-request-and-its-cached-input-on-its-usage) 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](/docs/api-reference/errors#coding-plan-limit).

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](/docs/api-reference/anthropic-messages#coding-plan-funding).