# Plan usage and funding

[Open models](https://www.rightnowai.co/docs/open-models) / [Plan usage and funding](https://www.rightnowai.co/docs/open-models/usage)

Updated 2026-11-11

**Connection**

| Connection | Value |
| --- | --- |
| API base | `https://api.runinfra.ai/v1` |
| Workspace key | `rp_...` |
| Process variable | `RUNINFRA_GATEWAY_KEY` |
| Billing | The existing funding rules of your open-model account. |

**Text**

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

Coding plans retired for new customers on 2026-11-03; existing holders are served until their own paid period ends, subject to payment and eligibility conditions. Read their remaining limits, credits after limits, and funding policy for the open-models service with a workspace API key. This endpoint is read-only. Use [GET /v1/credits](https://www.rightnowai.co/docs/open-models/credits) for the credit balance and budget, including when no coding plan exists.

## Request

**Shell**

```shell
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.

**JSON**

```json
{
  "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"]
}
```

**Reference 43**

| 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.

**Reference 56**

| 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. Always `false` since coding plans retired on 2026-11-03. Before then, `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.

**Reference 81**

| 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

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.

**Plan response headers**

| Header | Meaning |
| --- | --- |
| `x-runinfra-plan` | Plan tier. |
| `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. |

## 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](https://www.rightnowai.co/docs/open-models/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 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](https://www.rightnowai.co/docs/open-models/errors#retired-plan-limit-recovery).

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](https://www.rightnowai.co/docs/open-models/messages#coding-plan-funding).

[Source reference](https://runinfra.ai/docs/api-reference/usage?utm_source=rightnowai.co&utm_medium=referral&utm_content=docs-open-models)

## Next

[Open-model errors](https://www.rightnowai.co/docs/open-models/errors)