Responses & Usage — Aivana Docs

API Reference

Responses & Usage

What a successful request returns, and how to read the usage it reports.

Response fields

Field	Description
id	Identifier of this run. Quote it, with request_id, when you contact support.
request_id	Identifier of this request. The same value comes back in the X-Request-Id response header.
answer	The synthesized answer. With JSON Schema (Strict), the compact JSON of structured: the same value, serialized.
usage	Tokens and credits for this run. See below.
latency_ms	Time taken, in milliseconds.
finish_reason	Why the answer ended: stop for a normal finish, length when it hit max_tokens or was cut short on Aivana's side.
notices	What you or your user may need to know about the answer, each a code and a message you can show as it is. Always present; empty when there is nothing to say.
structured	The answer as a parsed JSON object, when you asked for structured output. With JSON Schema (Strict) it is the object validated against your schema, never null on a success. With prompt-defined JSON it is null if the answer wasn't a JSON object. See Structured output on Parameters.
structured_error	Why the answer couldn't be parsed as a JSON object. null when parsing worked.
trace	The Intelligence Trace, only when you asked for it.

Usage

Field	Description
input_tokens	Tokens in your request, including your history and any attached files.
cached_tokens	The part of input_tokens the run reused from cache. It is billed at the cached-input rate, and is 0 when nothing was reused.
output_tokens	Tokens in the answer.
credits	What the run was charged. See Pricing & Billing.

With JSON Schema (Strict), your schema counts once toward input_tokens, at about four characters a token of the schema as compact JSON, however Aivana produces the answer. A request that fails with structured_output_failed, or is refused for its schema, isn't charged. See Structured Outputs.

cached_tokens is part of input_tokens, not in addition to it. Cache reuse is automatic and may expire after inactivity, so identical follow-ups aren't guaranteed a cached part.

The usage and credits an API response returns are your actual Aivana usage and charge. Comparisons with external benchmarks are calculated separately in Usage & Insights and are not part of an individual Generate response.

Notices

Today there is one notice code, web_search_off: the question asked for the web (for example "search the web for…" or a link to read), but web search was off for the request, so the answer was written without searching. Set web_search to true to allow a search. A streamed response carries the same notices in its done event.

Example

json

{
  "id": "gen_...",
  "request_id": "req_...",
  "answer": "...",
  "usage": { "input_tokens": 5000, "output_tokens": 2000, "cached_tokens": 0, "credits": 0.013 },
  "latency_ms": 6120,
  "finish_reason": "stop",
  "notices": [
    { "code": "web_search_off", "message": "..." }
  ]
}

Learn more

Parameters

Every option the Generate API accepts.

View in Docs

Quickstart Guide

Get your key and make your first request in minutes.

View in Docs

Managing API Keys

Learn how to create and revoke API keys in Aivana AI Studio.

Create Key View in Docs

Still have questions? We are here to help!