Accounts & billing

Usage accounting

What you're charged for, what every usage field means, how cost is calculated, and how to look up the record of any request.

On this page

What you're charged for
The usage object
How cost is calculated
Exact decimals
Reservations
Usage in streams
Look up a generation
Usage in the dashboard
Next steps

Every response reports what was measured and what it cost, in the key's currency. GET /generation returns the authoritative record of any request after the fact.

What you're charged for

You pay for output delivered to you, at the offer's listed rates, based on the provider's reported usage as validated by Numes.

No output, no charge. A request that fails before delivering output costs nothing, and the funds held for it are released.
Only the endpoint that delivers is charged. If one endpoint fails before output and another then serves the request, you pay only for the one that served it. Output from two endpoints is never combined. See Fallbacks.
Delivered output is charged whatever it says. A refusal, or output that fails your own validation such as invalid JSON, is charged like any other response.

GET /generation is the authoritative record of what each request delivered and cost.

The usage object

Every buffered response and the final chunk of every stream include usage. It can't be switched off; stream_options.include_usage and usage.include are accepted and ignored.

usage

{  "prompt_tokens": 1204,  "completion_tokens": 312,  "total_tokens": 1516,  "token_count_basis": "provider_native",  "native_tokens": {    "prompt_tokens": 1204,    "completion_tokens": 312,    "reasoning_tokens": 0,    "cache_read_tokens": 1024  },  "cost": 0.002667,  "cost_details": { "upstream_inference_cost": 0.002667 },  "prompt_tokens_details": { "cached_tokens": 1024 },  "completion_tokens_details": { "reasoning_tokens": 0 }}

usage

prompt_tokensinteger

Billed input tokens.

completion_tokensinteger

Billed output tokens, including any reasoning.

total_tokensinteger

prompt_tokens + completion_tokens.

token_count_basisstring

provider_native when the counts are the provider's validated token counts, gateway_estimate otherwise.

native_tokensobject

The provider's validated token counts, when reported.

Show child attributes

prompt_tokensinteger: Input tokens.
completion_tokensinteger: Output tokens.
reasoning_tokensinteger: Reasoning tokens within the output, when reported.
cache_read_tokensinteger: Input tokens read from the provider's cache, when reported.
cache_write_tokensinteger: Input tokens written to the provider's cache, when reported.

gateway_billing_unitsobject

Billed quantities on some older requests, with prompt_units, completion_units and reasoning_units. Absent on current requests.

usage_meterstring

An identifier of the offer's billing basis. Treat it as opaque.

costnumber

Total charge in the key's currency: US dollars for USD keys, sats for BTC keys.

cost_detailsobject

Breakdown of cost.

Show child attributes

upstream_inference_costnumber: The provider's share of cost.

prompt_tokens_detailsobject

Cache split of the input, when known.

Show child attributes

cached_tokensinteger: Tokens read from cache.
cache_write_tokensinteger: Tokens written to cache.

completion_tokens_detailsobject

Present when the reasoning split is known.

Show child attributes

reasoning_tokensinteger: Reasoning tokens within the output.

input_imagesinteger

Input images. Only when non-zero.

output_imagesinteger

Generated images. Only when non-zero.

input_audio_secondsnumber

Input audio duration. Only when non-zero.

output_audio_secondsnumber

Output audio duration. Only when non-zero.

hosted_tool_usageobject

Hosted-tool quantities by billed item, such as a number of searches. Only when a hosted tool was billed.

Dedicated media endpoints report usage in their own units: images for image generation, input characters and output audio seconds for speech, and audio seconds for transcription. Embeddings report prompt_tokens, total_tokens and cost.

How cost is calculated

Text

cost = Σ (billed quantity × offer rate)   for each priced dimension

Offer rates are the per-unit prices in GET /models and the endpoints list: per input and output token, plus any per-request, image, audio, cache, reasoning or hosted-tool rate.
No markup on requests. The platform fee is charged when you buy credits, so cost_details.upstream_inference_cost equals cost. See Credits and payments.
Prices are locked per request. A price change while a request runs doesn't affect it.
Reasoning counts as output, charged at the offer's reasoning rate when it has one and at the output rate otherwise. See Reasoning.
Prompt caching. Input read from or written to the provider's cache is charged at the offer's cache rates, which are never higher than its input rate, based on the cache usage Numes accepts from the provider's response. The saving appears as cache_discount on the generation and Saved by cache in Logs. See Prompt caching.

Exact decimals

Costs are exact decimal values in the key's currency, written as JSON numbers. Parse them as decimals if you add them up, for example with json.loads(text, parse_float=Decimal) in Python. Never add USD and BTC amounts together.

Reservations

Before a request runs, an upper bound of its cost is held against your balance and spending limits. Unused funds are released when it completes, and only the actual charge is taken. A request whose upper bound exceeds your available funds or a spending limit is rejected with 402 before it runs. See Credits and payments.

Usage in streams

A successful stream ends with a usage-only chunk whose choices array is empty, followed by data: [DONE]. If a stream ends with an error or your connection drops, there's no usage chunk; look up the generation instead. See Streaming for the event format.

Look up a generation

GET /generation returns the record of one request: outcome, delivery, final usage, cost and every endpoint tried. After a disconnect or a mid-stream error, it's the authoritative record of what was delivered and charged.

GET/api/v1/generationReference →

The generation ID is the id of a chat completion and the value of the X-Generation-Id response header, present on every response that started delivering. Call it with an inference key from the same account; another account's generation returns 404.

curl "https://api.numes.ai/api/v1/generation?id=0f5b5c9a-3a7e-4c6f-9b1d-2e8f7a6c5d41" \  -H "Authorization: Bearer $NUMES_API_KEY"

Show an example response

JSON

{  "data": {    "id": "0f5b5c9a-3a7e-4c6f-9b1d-2e8f7a6c5d41",    "request_id": "7c1e0a9b2d3f4e5a6b7c8d9e0f1a2b3c",    "model": "openai/gpt-6-luna",    "provider_name": "Example Provider",    "provider_slug": "example-provider",    "endpoint": "example-provider/primary",    "created_at": "2026-09-28T10:15:02Z",    "completed_at": "2026-09-28T10:15:05Z",    "outcome": "success",    "streamed": true,    "cancelled": false,    "delivered_output": true,    "usage": {      "prompt_tokens": 1204,      "completion_tokens": 312,      "total_tokens": 1516,      "cost": 0.002667,      "cost_details": { "upstream_inference_cost": 0.002667 }    },    "total_cost": 0.002667,    "upstream_inference_cost": 0.002667,    "cache_discount": 0.000921,    "attempts": [      {        "ordinal": 1,        "provider_name": "Other Provider",        "provider_slug": "other-provider",        "endpoint": "other-provider/main",        "dispatch_state": "confirmed",        "financial_status": "finalized",        "outcome": "failed",        "failure_class": "rate_limited",        "delivered_output": false,        "cancelled": false,        "usage": { "prompt_tokens": 0, "completion_tokens": 0 },        "total_cost": 0,        "upstream_inference_cost": 0      },      {        "ordinal": 2,        "provider_name": "Example Provider",        "provider_slug": "example-provider",        "endpoint": "example-provider/primary",        "dispatch_state": "confirmed",        "financial_status": "finalized",        "outcome": "success",        "delivered_output": true,        "cancelled": false,        "usage": { "prompt_tokens": 1204, "completion_tokens": 312, "cache_read_tokens": 1024 },        "total_cost": 0.002667,        "upstream_inference_cost": 0.002667      }    ]  }}

Response `data`

idstring

Generation ID (a UUID).

request_idstring

The request's X-Request-Id.

modelstring

Requested model ID.

provider_namestring | null

Display name of the provider that served the response; null if none did.

provider_slugstring | null

Routing slug of that provider.

endpointstring | null

The serving endpoint as a provider/endpoint routing selector.

created_atstring

When the request was accepted.

completed_atstring | null

When it finished; null while running.

outcomestring

Final result; see the table below.

streamedboolean

Whether the request used streaming.

cancelledboolean

Whether you cancelled or disconnected.

delivered_outputboolean

Whether any billable output reached you.

usageobject

Final billed usage, in the same shape as the response usage without the provider's raw counts.

usage_meterstring

Opaque identifier of the billing basis.

total_costnumber

Total charge in the key's currency.

upstream_inference_costnumber

The provider's share of total_cost.

cache_discountnumber

Amount saved by prompt caching.

attemptsobject[]

Every endpoint tried, in order.

Show child attributes

ordinalinteger: Attempt number, starting at 1. Numbers can have gaps.
provider_namestring: Display name of the provider tried.
provider_slugstring: Routing slug of the provider tried.
endpointstring: Endpoint tried, as provider/endpoint.
dispatch_statestring: confirmed when the request reached the provider, uncertain when that couldn't be confirmed.
financial_statusstring: finalized, or pending while the charge is being finalized.
outcomestring: Result of this attempt.
failure_classstring: Short code for why it failed, such as rate_limited. Omitted on success.
delivered_outputboolean: Whether this attempt delivered billable output.
cancelledboolean: Whether the attempt ended because of a cancel.
usageobject: Billed quantities for this attempt: prompt_tokens, completion_tokens, and when present reasoning_tokens, cache_read_tokens, cache_write_tokens, input_images, output_images and input_audio_milliseconds. Zero while pending.
total_costnumber: What this attempt cost. Absent while pending.
upstream_inference_costnumber: The provider's share. Absent while pending.

`outcome`	Meaning
`in_progress`	Still running, or the charge isn't final yet; usage and cost read zero
`success`	Completed and delivered
`cancelled`	You cancelled or disconnected
`partial_failure`	Failed after some output was delivered
`failed`	Failed before any output; not charged
`delivery_failure`	The response couldn't be fully delivered
Any other value	The request ended without a normal result

For every outcome, total_cost is what you were charged. A pending charge isn't the same as zero: poll again until financial_status is finalized.

The record never contains prompt or response content, keys or session IDs.

Usage in the dashboard

Every request also appears in Logs with its Usage and cost panel. See Activity and logs.

Next steps

Credits and paymentsBalances, reservations and spending limits.StreamingThe event format and cancellation.Prompt cachingEarn cache discounts.Activity and logsExplore spend across keys, models and apps.Get a generationFull schema of the generation record.