# Generation metadata and actual charges

Source: https://provod.ai/en/docs/generation-metadata

**`GET /v1/generation`**

Retrieve a terminal request’s metadata and actual charge using its saved gen-… ID.

## Authentication

`Authorization: Bearer <API_KEY>` accepts an inference or management key. An inference key reads only its own generations; a management key reads within its workspace. Private image and video records additionally enforce owner access. `X-Org-Id` is unsupported.

## Query parameters


| Field | Type              | Description                                                                                                              |
| ----- | ----------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `id`  | string · required | Up to 128 characters; must match ^gen-\[0-9A-Za-z-]+$. Use x-generation-id or provod.generation\_id, not the resp-\* ID. |


## Response · 200

Fields inside data:


| Field                                                                                           | Type                      | Description                                                                 |
| ----------------------------------------------------------------------------------------------- | ------------------------- | --------------------------------------------------------------------------- |
| `id, model`                                                                                     | string                    | Public generation and model identifiers.                                    |
| `created_at`                                                                                    | number                    | Unix timestamp in seconds.                                                  |
| `currency`                                                                                      | string                    | Billing currency.                                                           |
| `total_cost, usage`                                                                             | number \| null            | Actual total charge, null while pending. Two aliases for the same amount.   |
| `billing`                                                                                       | object                    | Exact settled or pending amounts. See the billing schema below.             |
| `num_media_prompt, num_media_completion`                                                        | number \| null            | Persisted media input/output counts when known.                             |
| `upstream_inference_cost`                                                                       | null                      | Provider cost is not exposed.                                               |
| `status, origin`                                                                                | string · optional         | Recorded generation state and origin when available.                        |
| `generation_time`                                                                               | number · optional         | Duration in seconds.                                                        |
| `native_tokens_prompt, native_tokens_completion, native_tokens_reasoning, native_tokens_cached` | number \| null · optional | Recorded token counters. Absence does not establish a zero monetary charge. |
| `cache_discount`                                                                                | number · optional         | Compatibility field; not a monetary component breakdown.                    |


## Request example

Replace the illustrative ID with your request’s generation ID.




TypeScript



Python



cURL




```typescript
const response = await fetch("https://api.provod.ai/v1/generation?id=gen-example-request", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
  },
});
if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
console.log(await response.json());
```



```python
import json
import os
from urllib.request import Request, urlopen

request = Request(
    "https://api.provod.ai/v1/generation?id=gen-example-request",
    method="GET",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
with urlopen(request) as response:
    print(json.load(response))
```



```bash
curl --fail-with-body --silent --show-error -X GET \
  "https://api.provod.ai/v1/generation?id=gen-example-request" \
  -H "Authorization: Bearer ${API_KEY}"
```



## Errors


| HTTP  | Error        | Cause                                                                                       |
| ----- | ------------ | ------------------------------------------------------------------------------------------- |
| `401` | Unauthorized | Missing, invalid, disabled, revoked or expired key. The `X-Org-Id` header is also rejected. |
| `403` | Forbidden    | Wrong key kind or insufficient workspace access.                                            |
| `400` | Bad Request  | Missing or malformed id.                                                                    |
| `404` | Not Found    | Record is not terminal, does not exist or is outside the credential’s access boundary.      |


Authentication error example:

```json
{
  "message": "Invalid API key",
  "error": "Unauthorized",
  "statusCode": 401
}
```

Errors and disconnects become readable after the terminal record is persisted. A 404 does not prove there was no charge. Retry this read with bounded backoff; do not repeat inference to recover billing.

Operation error example:

```json
{
  "message": "Generation not found",
  "error": "Not Found",
  "statusCode": 404
}
```

## Actual charges, estimates, and exact decimals

The `200` response is wrapped in `data`. Its billing fields are:

```typescript
type Billing = {
  status: "settled" | "pending";
  currency: string;
  usage_charge: string | null;
  guardrail_charge: string | null;
  total_charge: string | null;
};
type GenerationMoney = {
  total_cost: number | null;
  usage: number | null;
  currency: string;
  billing: Billing;
};
```


| Field                      | Meaning                                                                                                                |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `billing.status`           | `settled` means the charge is known; `pending` means settlement evidence is not yet sufficient.                        |
| `billing.currency`         | Billing currency of this generation; use the returned value rather than a hard-coded conversion.                       |
| `billing.usage_charge`     | Actual customer `USAGE_CHARGE`, not a provider cost or token-price estimate.                                           |
| `billing.guardrail_charge` | Actual `GUARDRAIL_CHARGE` linked through this generation's economics record; unrelated workspace charges are excluded. |
| `billing.total_charge`     | Sum of the known usage and linked guardrail charges when settled.                                                      |
| `total_cost`, `usage`      | Legacy numeric aliases for the total, or `null` while unknown; prefer decimal strings for exact accounting.            |


All non-null amounts inside `billing` are decimal **strings with eight fractional digits** in the returned currency. Use decimal arithmetic; do not parse them into binary floating point for financial reconciliation. Guardrail charges must not be omitted or added a second time to `total_charge`.

### Settled paid generation

Synthetic excerpt only: these invented amounts demonstrate the wire shape, not production prices or a real transaction. Other metadata fields are omitted.

```json
{
  "data": {
    "id": "gen-example-request",
    "total_cost": 0.0125,
    "usage": 0.0125,
    "currency": "RUB",
    "billing": {
      "status": "settled",
      "currency": "RUB",
      "usage_charge": "0.01000000",
      "guardrail_charge": "0.00250000",
      "total_charge": "0.01250000"
    }
  }
}
```

### Missing settlement is not free

Synthetic `billing` object for a completed request without sufficient settlement evidence:

```json
{
  "status": "pending",
  "currency": "RUB",
  "usage_charge": null,
  "guardrail_charge": null,
  "total_charge": null
}
```

Unknown money remains `null`; neither an absent ledger entry nor a zero estimate proves the request was free. Re-read the same generation after settlement; do not send a new inference request just to recover billing.

### Proven free generation

Only an explicitly proven free completion has settled zero amounts. Synthetic `billing` object:

```json
{
  "status": "settled",
  "currency": "RUB",
  "usage_charge": "0.00000000",
  "guardrail_charge": "0.00000000",
  "total_charge": "0.00000000"
}
```

`upstream_inference_cost` remains `null`: provider economics are not public customer billing. For text requests, `created_at` is Unix seconds, `generation_time` is seconds, and `native_tokens_*` are counters. Media counters describe persisted inputs/outputs when available; unknown counters are `null`. Image masks and generated thumbnails are not output usage evidence.

## Billing in JSON inference responses

JSON responses for Chat Completions, Anthropic Messages, and Responses carry an additive top-level `provod` extension. Standard protocol fields remain in place. Synthetic extension-only excerpt:

```json
{
  "provod": {
    "generation_id": "gen-example-request",
    "billing": {
      "status": "settled",
      "currency": "RUB",
      "usage_charge": "0.01000000",
      "guardrail_charge": "0.00250000",
      "total_charge": "0.01250000"
    }
  }
}
```

`provod.generation_id` is the lookup ID. `provod.billing` uses the same status, currency, eight-decimal string fields and `null` semantics as `/v1/generation`. Clients that discard unknown fields may need the raw response to retain this extension.

## Streaming boundaries and disconnect recovery

The stream's final billing payload contains the same `provod` extension. Read through the protocol's terminal boundary, rather than treating a finish reason or last text token as the settled bill:

```text
Chat Completions: settlement -> billing chunk.provod -> data: [DONE]
Anthropic Messages: settlement -> message_stop.provod
Responses: settlement -> response.completed.response.provod
```

Settlement is awaited before terminal delivery. Chat Completions sends a separate billing chunk before `[DONE]`. Native Anthropic Messages carries `provod` on the `message_stop` data object itself. Responses carries `response.provod` inside the terminal event (`response.completed` on success, or the corresponding terminal status). Do not stop parsing before those terminal payloads. Ordinary token/usage events are not a substitute for the final billing object.

Synthetic Chat Completions SSE tail with `stream_options.include_usage` omitted. Earlier token frames are omitted; blank lines delimit events. The model, timestamp, ID and money are illustrative, not a real request. The final billing chunk is sent even when token-usage reporting was not requested.

```text
data: {"id":"gen-example-request","object":"chat.completion.chunk","created":1794268800,"model":"example/model","choices":[],"usage":{"prompt_tokens":10,"completion_tokens":5,"total_tokens":15,"cost":0.0125,"currency":"RUB"},"provod":{"generation_id":"gen-example-request","billing":{"status":"settled","currency":"RUB","usage_charge":"0.01000000","guardrail_charge":"0.00250000","total_charge":"0.01250000"}}}

data: [DONE]

```

Synthetic native Messages terminal frame:

```text
event: message_stop
data: {"type":"message_stop","provod":{"generation_id":"gen-example-request","billing":{"status":"settled","currency":"RUB","usage_charge":"0.01000000","guardrail_charge":"0.00250000","total_charge":"0.01250000"}}}

```

Synthetic Responses terminal excerpt; other response and event fields are omitted. Read `response.provod`, not `event.provod`:

```text
event: response.completed
data: {"type":"response.completed","response":{"id":"resp-example","status":"completed","provod":{"generation_id":"gen-example-request","billing":{"status":"settled","currency":"RUB","usage_charge":"0.01000000","guardrail_charge":"0.00250000","total_charge":"0.01250000"}}}}

```

A disconnected client cannot receive a final bill on a closed socket. Persist the generation ID as soon as available. After a disconnect, use `GET /v1/generation` with the original inference key or an authorized management key. A paid final `499` can then be reconciled without rerunning the model. `404` is not proof of a zero charge: verify the key and workspace, then retry the lookup after finalization with bounded backoff. Do not blindly retry inference after output has started; it can create a second charge.

## Workspace reporting

`/v1/activity` and `/v1/analytics/query` aggregate actual debits, including paid failures. Financial buckets use posting time; refunds remain separate. See [management reporting](/en/docs/management-keys) for filters and limits.

## Related articles

* [Management keys and workspace billing](/en/docs/management-keys)
* [API key balance and usage](/en/docs/api-key-usage)
* [API authentication](/en/docs/authentication)

## Cost in API responses

Chat Completions and Responses expose the actual final charge as `usage.cost` and its currency as `usage.currency`. Pending settlement has a `null` cost. `provod.billing.total_charge` is the same amount as an exact eight-place decimal string; do not add these representations together. Supplier monetary fields are not forwarded as customer charges.

Chat Completions sends final `usage` and `provod` before `[DONE]`, even without `stream_options.include_usage`. It does not publish cost before settlement. Save `x-generation-id` immediately; Chat also uses it as the first stream frames' `id`. Responses exposes `provod.generation_id` in the initial event while preserving its own `resp-*` ID. After disconnects, poll `/v1/generation?id=...` with bounded backoff; `404` or `pending` does not mean free. Never rerun inference just to retrieve its charge.

The contract exposes usage debit and a separately charged guardrail component. It does **not** expose authoritative monetary input/output/cache read/write/reasoning or extra-operation breakdowns: historical component evidence is unavailable. Token counters do not replace that breakdown. Later refunds do not rewrite the original charge. Use `/v1/analytics/query` or `/v1/activity` for aggregated actual spending.

## Troubleshooting


**The generation returns 404 after a disconnect**


Verify the exact ID, the original inference key or scoped management key, workspace and media owner. Retry the read after finalization with bounded backoff. A missing record is not a free request; do not repeat inference to recover billing.


**A management request returns 403**


Confirm the endpoint accepts management keys and the key has the correct workspace scope. Cabinet session permissions and management Bearer authorization are different. Do not send `X-Org-Id` to switch workspaces.
