Chat

Get generation

Retrieve the record of one request — its outcome, delivery, usage and final cost — by its generation ID.

GEThttps://api.numes.ai/api/v1/generation

Use the id from a response or the X-Generation-Id header. This is the authoritative record of what was delivered and charged, including after a disconnect or a mid-stream error. Generations belong to your account: another account's ID returns 404. The record never contains prompts, outputs or keys. Guide: Usage accounting.

outcome is in_progress until the request finishes, then a final value such as success, cancelled or failed. Treat any final value other than success as unsuccessful, and read delivered_output and total_cost for what was delivered and charged. attempts lists each endpoint that was tried; while an attempt's financial_status is pending, its cost fields are omitted. A pending charge isn't a zero charge.

Authorization

AuthorizationheaderRequired

Bearer inference key. Charges settle in the key's billing currency. Authorization: Bearer $NUMES_API_KEY

Headers

X-Request-Idstring: Correlation ID, not an idempotency key. Inference request IDs recorded with a generation are unique per account. A traffic-admitted request reusing a recorded ID returns 400 invalid_request. Traffic admission rejection takes precedence over this conflict, including for reused IDs; it performs no generation lookup and writes no generation, result or attempt. Rate-limit rejection returns 429 rate_limited with Retry-After; an inference limiter outage retains 500 server.
Length1–128

Query parameters

idstring<uuid>Required

Responses

200Generation metadata visible to the owning accountapplication/json

Headers

X-Request-Idstring: Correlation identifier assigned or accepted by the service.

BodyGenerationResponseapplication/json

dataobjectRequired

Show18 child attributes

idstring<uuid>Required

request_idstringRequired

modelstringRequired

Length≤ 393

Pattern^[a-z0-9][a-z0-9._-]{0,99}/[A-Za-z0-9][A-Za-z0-9._:-]{0,291}$

created_atstring<date-time>Required

outcomestringRequired

streamedbooleanRequired

cancelledbooleanRequired

delivered_outputbooleanRequired

usageobjectRequired

Show16 child attributes

prompt_tokensintegerRequired

Range≥ 0

completion_tokensintegerRequired

Range≥ 0

total_tokensintegerRequired

Range≥ 0

costnumberRequired

Settled cost in the inference key's immutable billing currency. For BTC keys, 1 is one satoshi and precision is one micro-satoshi.

Range≥ 0

usage_meterstring

Opaque identifier of the billing basis this request was charged under. Treat it as a label; the charged amounts are in the cost fields.

token_count_basisenum<string>

One ofprovider_nativegateway_estimate

gateway_billing_unitsobject

Historical gateway billing quantities; absent for current native-meter inference.

Show3 child attributes

prompt_unitsinteger<int64>Required: Range≥ 0
completion_unitsinteger<int64>Required: Range≥ 0
reasoning_unitsinteger<int64>Required: Range≥ 0

native_tokensobject

Validated upstream native-token usage. Current native meters price these counts; reasoning partitions completion and cache partitions prompt.

Show5 child attributes

prompt_tokensinteger<int64>Required: Range≥ 0
completion_tokensinteger<int64>Required: Range≥ 0
reasoning_tokensinteger<int64>: Range≥ 0
cache_read_tokensinteger<int64>: Range≥ 0
cache_write_tokensinteger<int64>: Range≥ 0

prompt_tokens_detailsobject

Show3 child attributes

cached_tokensinteger: Range≥ 0
cache_write_tokensinteger: Range≥ 0
audio_tokensinteger: Range≥ 0

completion_tokens_detailsobject

Show2 child attributes

reasoning_tokensinteger: Range≥ 0
audio_tokensinteger: Range≥ 0

cost_detailsobject

Show3 child attributes

upstream_inference_costnumberRequired: Range≥ 0
upstream_inference_prompt_costnumber: Range≥ 0
upstream_inference_completions_costnumber: Range≥ 0

input_imagesinteger

Range≥ 0

output_imagesinteger

Range≥ 0

input_audio_secondsnumber

Range≥ 0

output_audio_secondsnumber

Range≥ 0

hosted_tool_usagemap<string, number>

Exact namespaced hosted-tool SKU quantities attributable to this response.

total_costnumberRequired

Range≥ 0

upstream_inference_costnumberRequired

Range≥ 0

cache_discountnumberRequired

attemptsarray<object>Required

Show14 child attributes

ordinalintegerRequired

Range≥ 1

dispatch_stateenum<string>Required

Actual inference-envelope write or an explicitly uncertain provider handoff.

One ofconfirmeduncertain

financial_statusenum<string>Required

Pending attempts omit cost fields until financial finalization.

One ofpendingfinalized

provider_namestringRequired

provider_slugstringRequired

endpointstringRequired

outcomestringRequired

delivered_outputbooleanRequired

cancelledbooleanRequired

usageobjectRequired

Settled attempt usage; zero while accounting is pending.

Show12 child attributes

prompt_tokensintegerRequired: Range≥ 0
completion_tokensintegerRequired: Range≥ 0
reasoning_tokensinteger: Range≥ 0
cache_read_tokensinteger: Range≥ 0
cache_write_tokensinteger: Range≥ 0
input_imagesinteger: Range≥ 0
output_imagesinteger: Range≥ 0
input_audio_millisecondsinteger: Range≥ 0
output_audio_millisecondsinteger: Range≥ 0
input_charactersinteger: Range≥ 0
requestsinteger: Range≥ 0
skusmap<string, string>

usage_meterstring

failure_classstring

total_costnumber

Final customer charge; absent while financial status is pending.

Range≥ 0

upstream_inference_costnumber

Final provider cost; absent while financial status is pending.

Range≥ 0

usage_meterstring

Opaque identifier of the selected offer's billing basis.

provider_namestring | null

provider_slugstring | null

endpointstring | null

completed_atstring<date-time> | null

ErrorCompatible error envelopeapplication/json

Headers

X-Request-Idstring: Correlation identifier assigned or accepted by the service.
Retry-Afterinteger: Optional delay in seconds for retryable rate or availability errors.
Range≥ 1

BodyErrorResponseapplication/json

errorobjectRequired

Show3 child attributes

codeintegerRequired
messagestringRequired
metadataobject

openrouter_metadataobject

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

Response

{  "data": {    "id": "0f5b5c9a-3a7e-4c6f-9d1e-2b8f7a6c5d4e",    "request_id": "7c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f",    "model": "openai/gpt-6-luna",    "provider_name": "Example Provider",    "provider_slug": "example-provider",    "endpoint": "example-provider/primary",    "created_at": "2026-09-28T12:00:00Z",    "completed_at": "2026-09-28T12:00:01Z",    "outcome": "success",    "streamed": true,    "cancelled": false,    "delivered_output": true,    "usage": {      "prompt_tokens": 27,      "completion_tokens": 24,      "total_tokens": 51,      "cost": 0.000013,      "cost_details": { "upstream_inference_cost": 0.000013 }    },    "total_cost": 0.000013,    "upstream_inference_cost": 0.000013,    "cache_discount": 0,    "attempts": [      {        "ordinal": 1,        "dispatch_state": "confirmed",        "financial_status": "finalized",        "provider_name": "Example Provider",        "provider_slug": "example-provider",        "endpoint": "example-provider/primary",        "outcome": "success",        "delivered_output": true,        "cancelled": false,        "usage": { "prompt_tokens": 27, "completion_tokens": 24 },        "total_cost": 0.000013,        "upstream_inference_cost": 0.000013      }    ]  }}