provod.ai / docs
API

Generation metadata and actual charges

Read settled generation charges, billing breakdowns and streaming recovery with an inference or scoped management key.

Last updated on

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

FieldTypeDescription
idstring · requiredUp 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:

FieldTypeDescription
id, modelstringPublic generation and model identifiers.
created_atnumberUnix timestamp in seconds.
currencystringBilling currency.
total_cost, usagenumber | nullActual total charge, null while pending. Two aliases for the same amount.
billingobjectExact settled or pending amounts. See the billing schema below.
num_media_prompt, num_media_completionnumber | nullPersisted media input/output counts when known.
upstream_inference_costnullProvider cost is not exposed.
status, originstring · optionalRecorded generation state and origin when available.
generation_timenumber · optionalDuration in seconds.
native_tokens_prompt, native_tokens_completion, native_tokens_reasoning, native_tokens_cachednumber | null · optionalRecorded token counters. Absence does not establish a zero monetary charge.
cache_discountnumber · optionalCompatibility field; not a monetary component breakdown.

Request example

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

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());

Errors

HTTPErrorCause
401UnauthorizedMissing, invalid, disabled, revoked or expired key. The X-Org-Id header is also rejected.
403ForbiddenWrong key kind or insufficient workspace access.
400Bad RequestMissing or malformed id.
404Not FoundRecord is not terminal, does not exist or is outside the credential’s access boundary.

Authentication error example:

{
  "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:

{
  "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:

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;
};
FieldMeaning
billing.statussettled means the charge is known; pending means settlement evidence is not yet sufficient.
billing.currencyBilling currency of this generation; use the returned value rather than a hard-coded conversion.
billing.usage_chargeActual customer USAGE_CHARGE, not a provider cost or token-price estimate.
billing.guardrail_chargeActual GUARDRAIL_CHARGE linked through this generation's economics record; unrelated workspace charges are excluded.
billing.total_chargeSum of the known usage and linked guardrail charges when settled.
total_cost, usageLegacy 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.

{
  "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:

{
  "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:

{
  "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:

{
  "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:

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.

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:

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:

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 for filters and limits.

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

On this page