# Get generation

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

`GET https://api.numes.ai/api/v1/generation`

Source: https://0.0.0.0:3000/docs/api-reference/chat/get-generation
Authorization: Bearer inference key

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](/docs/account/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.

```request
{
  "method": "GET",
  "path": "/generation",
  "query": { "id": "0f5b5c9a-3a7e-4c6f-9d1e-2b8f7a6c5d4e" }
}
```

```json title="Response 200"
{
  "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
      }
    ]
  }
}
```

## Headers

- `X-Request-Id` (string; Length 1–128): 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.

## Query parameters

- `id` (string<uuid>; required)

## Response 200 (application/json)

- `data` (object; required)
  - `usage_meter` (string): Opaque identifier of the selected offer's billing basis.
  - `id` (string<uuid>; required)
  - `request_id` (string; required)
  - `model` (string; required; Length ≤ 393; Pattern ^[a-z0-9][a-z0-9._-]{0,99}/[A-Za-z0-9][A-Za-z0-9._:-]{0,291}$)
  - `provider_name` (string | null)
  - `provider_slug` (string | null)
  - `endpoint` (string | null)
  - `created_at` (string<date-time>; required)
  - `completed_at` (string<date-time> | null)
  - `outcome` (string; required)
  - `streamed` (boolean; required)
  - `cancelled` (boolean; required)
  - `delivered_output` (boolean; required)
  - `usage` (object; required)
    - `usage_meter` (string): 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_basis` (enum<string>; one of provider_native, gateway_estimate)
    - `gateway_billing_units` (object): Historical gateway billing quantities; absent for current native-meter inference.
      - `prompt_units` (integer<int64>; required; Range ≥ 0)
      - `completion_units` (integer<int64>; required; Range ≥ 0)
      - `reasoning_units` (integer<int64>; required; Range ≥ 0)
    - `native_tokens` (object): Validated upstream native-token usage. Current native meters price these counts; reasoning partitions completion and cache partitions prompt.
      - `prompt_tokens` (integer<int64>; required; Range ≥ 0)
      - `completion_tokens` (integer<int64>; required; Range ≥ 0)
      - `reasoning_tokens` (integer<int64>; Range ≥ 0)
      - `cache_read_tokens` (integer<int64>; Range ≥ 0)
      - `cache_write_tokens` (integer<int64>; Range ≥ 0)
    - `prompt_tokens` (integer; required; Range ≥ 0)
    - `completion_tokens` (integer; required; Range ≥ 0)
    - `total_tokens` (integer; required; Range ≥ 0)
    - `cost` (number; required; Range ≥ 0): Settled cost in the inference key's immutable billing currency. For BTC keys, 1 is one satoshi and precision is one micro-satoshi.

    - `prompt_tokens_details` (object)
      - `cached_tokens` (integer; Range ≥ 0)
      - `cache_write_tokens` (integer; Range ≥ 0)
      - `audio_tokens` (integer; Range ≥ 0)
    - `completion_tokens_details` (object)
      - `reasoning_tokens` (integer; Range ≥ 0)
      - `audio_tokens` (integer; Range ≥ 0)
    - `cost_details` (object)
      - `upstream_inference_cost` (number; required; Range ≥ 0)
      - `upstream_inference_prompt_cost` (number; Range ≥ 0)
      - `upstream_inference_completions_cost` (number; Range ≥ 0)
    - `input_images` (integer; Range ≥ 0)
    - `output_images` (integer; Range ≥ 0)
    - `input_audio_seconds` (number; Range ≥ 0)
    - `output_audio_seconds` (number; Range ≥ 0)
    - `hosted_tool_usage` (map<string, number>): Exact namespaced hosted-tool SKU quantities attributable to this response.
  - `total_cost` (number; required; Range ≥ 0)
  - `upstream_inference_cost` (number; required; Range ≥ 0)
  - `cache_discount` (number; required)
  - `attempts` (array<object>; required)
    - `usage_meter` (string)
    - `ordinal` (integer; required; Range ≥ 1)
    - `dispatch_state` (enum<string>; required; one of confirmed, uncertain): Actual inference-envelope write or an explicitly uncertain provider handoff.
    - `financial_status` (enum<string>; required; one of pending, finalized): Pending attempts omit cost fields until financial finalization.
    - `provider_name` (string; required)
    - `provider_slug` (string; required)
    - `endpoint` (string; required)
    - `outcome` (string; required)
    - `failure_class` (string)
    - `delivered_output` (boolean; required)
    - `cancelled` (boolean; required)
    - `usage` (object; required): Settled attempt usage; zero while accounting is pending.
      - `prompt_tokens` (integer; required; Range ≥ 0)
      - `completion_tokens` (integer; required; Range ≥ 0)
      - `reasoning_tokens` (integer; Range ≥ 0)
      - `cache_read_tokens` (integer; Range ≥ 0)
      - `cache_write_tokens` (integer; Range ≥ 0)
      - `input_images` (integer; Range ≥ 0)
      - `output_images` (integer; Range ≥ 0)
      - `input_audio_milliseconds` (integer; Range ≥ 0)
      - `output_audio_milliseconds` (integer; Range ≥ 0)
      - `input_characters` (integer; Range ≥ 0)
      - `requests` (integer; Range ≥ 0)
      - `skus` (map<string, string>)
    - `total_cost` (number; Range ≥ 0): Final customer charge; absent while financial status is pending.
    - `upstream_inference_cost` (number; Range ≥ 0): Final provider cost; absent while financial status is pending.

## Response default (application/json)

- `error` (object; required)
  - `code` (integer; required)
  - `message` (string; required)
  - `metadata` (object)
- `openrouter_metadata` (object)