Skip to main content

Generations

One model loop each — the record every agent, session and conversation run is polled, audited and purged through.

Overview​

A generation is created for you: running an agent, posting to a session, or generating into a conversation each produce one. What you get back immediately is its id, because generation is background by default — so this module is where a run's status, result, transcript and cost attribution are read from afterwards.

This module is a verbatim mirror of the runtime: every field, method, status code and error shape is the runtime's own, re-rooted under the project in the path.

See the OpenAPI spec for the full endpoint and schema reference, or browse it rendered under API Reference → Generations.

Data Model​

Generation​

FieldTypeDescription
idstringPublic ID of the generation
project_idstringPublic ID of the project
agent_idstringPublic ID of the agent that ran this generation
trace_idstringPublic ID of the trace this generation belongs to
initiator_generation_idstring, nullablePublic ID of the generation that started this one: a sub-agent invocation, an approval continuation, a client-tool re-handoff or a memory-rule handler turn. Null for top-level generations.
chain_idstring, nullablePublic ID of the continuation chain this generation belongs to. Set on every member of a chain — the continuations and the root they descend from — and null on a generation that is not part of one.
conversation_idstring, nullablePublic ID of the conversation this turn served, or null for a generation started outside one — a direct call, a trigger, an orchestration node. This is the edge a memory assertion walks up to reach the conversation a fact was learned in.
session_idstring, nullablePublic ID of the session this generation was dispatched through, or null for a generation started outside one. This is the link a per-session cost reading follows; the session's own usage field reports the roll-up directly.
actor_idstring, nullablePublic ID of the end-user actor the generation was attributed to, or null when none was. Copied onto the generation's usage event.
started_by_principal_typestring, nullableWho started the generation
started_by_principal_idstring, nullablePublic id of that principal: the user (user_…), or for API key auth the key itself (key_…), so the record names which key acted.
acted_asobject, nullableThe principal the latest segment's tool calls ran as: the starter, or the agent when it runs under its own grant (run_as: agent). A caller who resumes the generation by submitting its tool outputs only narrows what it may do. A tool call an approval held runs, once approved, as this principal. Null when the segment ran with no principal.
acts_forobject, nullableThe opaque principal the starter acted for: the principal of the IAM token that started the generation, or the one an On-Behalf-Of assertion carried. started_by_principal_* names the key that minted the token. A resume keeps the starter's. Null when the starter named none.
statusrunning | requires_action | completed | failedLifecycle status of the generation
started_atstring (date-time)
completed_atstring (date-time), nullableWhen the generation reached a terminal state
last_activity_atstring (date-time), nullable
stop_reasonstring, nullableWhy the generation stopped. Either the model provider's own finish reason relayed unchanged ('stop', 'tool-calls', 'length', …) or one the platform names itself: 'max_steps' when the turn spent its whole step budget on tool calls, 'depth_guard' when a nested call exceeded the call depth, 'chain_limit' when a continuation chain reached its generation budget, or 'error' when the turn failed.
errorobject, nullableWhy the generation failed: AI_PROVIDER_ERROR for an upstream provider failure, GENERATION_FAILED for any other failure of the turn.
action_idstring, nullableLogical action label supplied on the generate request. Recorded on the generation's usage event for per-action spend rollups.
trigger_idstring, nullableTrigger that initiated the generation, when applicable
orchestration_run_idstring, nullableOrchestration run that dispatched the generation. Null for a standalone generation.
node_idstring, nullableNode within orchestration_run_id that dispatched the generation. Together with the run it forms the usage event's replay identity.
node_attemptinteger, nullableThe node's 1-based retry attempt, completing the run + node + attempt replay identity. A retried node produces one generation per attempt; this is what tells them apart. Null for a generation no orchestration node dispatched.
agent_versioninteger, nullableAgent config version that served this generation, resolved by the served-version resolver (see agent versions).
sourcestring, nullableWhat produced the generation besides production traffic: eval for an eval run, decider for a decider question. null for production traffic.
extractionobject, nullableWhat each memory rule bound to generations.completed wrote for this turn, keyed by the rule's id — a store may have several rules, and one flat pair of counts could not say which produced them. Absent when no rule fired. Rules bound to conversation_messages.generated are recorded only as memory assertions. The rows behind every count are listed by GET /v1/projects/{project_id}/generations/{generation_id}/memory-assertions, so the summary and what it summarizes can be reconciled.
tool_surfaceobject, nullableWhat this turn's tool definitions cost to send — the one part of a prompt no provider reports and no caller can derive, since the tool block is a constant inside the reported totals and identical on every step. Null when the surface was never measured: a generation from before the field, or a path that resolves none. That is not what tools: 0 means, which is a measured agent with nothing bound. Not a meter. estimated_tokens is an estimate and is never priced — usage and the usage events are the billing record.
retrievalobject[], nullableWhat knowledge_config retrieval injected into this turn, in the order it was injected: which document, at which version, and which chunk, or which memory. Written by the server at turn start and never writable; pointers only, never the text. Null when no retrieval ran — the agent has no knowledge_config, or the turn had neither a query nor a filter to search with. An empty array is a retrieval that ran and matched nothing. Not content: a content purge leaves it standing, and zero retention still writes it. document_version names an archived version, so the text the turn read stays readable after the document changes.
idempotency_keystring, nullableThe deduplication key the generation was started under, unique within the project and claimed for as long as the generation record exists. Null for a generation started without one.
usageobject, nullableWhat the turn cost: token counts and cost_usd for every event metered against this generation. Present on the single-generation read; omitted from the listing, where it would be a query per row. Null when nothing has been metered yet — a turn still in flight, or one whose metering failed. A turn is metered once at the end, so this is one event's figures in the ordinary case.
routingobject, nullableWhat the model route did for this generation. Present only when the agent resolves its model through a model_route_id.
metadataobjectCaller-owned key/value annotations, attached at create time (via the metadata field on the create-agent-generation request) or afterwards (via the update-generation request), and returned verbatim. The server writes nothing here: every piece of state it owns — usage attribution, the served agent version, the route's record, the extraction summary, internal recovery state — is a field of its own, so no key written here can reach platform state. Keys are never transformed, and no key is reserved.
content_redacted_atstring (date-time), nullableWhen the generation's content was purged. Non-null means metadata, error, extraction and the internal recovery state have been cleared, while the usage/audit skeleton — ids, timestamps, status, stop reason and the attribution fields — is preserved.
content_redacted_by_principal_typestring, nullableWho purged the content: user or api_key for a purge request, system for the retention sweep and for content never stored under zero retention.
content_redacted_by_principal_idstring, nullablePublic id of that principal — the API key's own id for key auth, so the record names which key acted. retention_sweep or zero_retention for system.
created_atstring (date-time)
updated_atstring (date-time)

Key Concepts​

Background by default​

A generate call answers 202 Accepted with a generation_id unless you pass wait=true. Poll GET /v1/projects/{project_id}/generations/{generation_id} until status leaves running:

  • completed — the result is on the generation, and on the conversation or session it ran in.
  • requires_action — a client-type tool is waiting on you; submit its output to resume the run.
  • failed — read error.message.

Your first agent generation polls one to completed; Run tools in your own code parks one at requires_action and resumes it.

A resume only narrows. Submitting tool outputs, directly or through a session, also needs generations:ResumeGeneration on the generation. The resumed segment runs under the generation's stored authority held to the submitter's, so a submitter wider than the starter adds nothing and acted_as keeps naming the starter. A generation that stores no authority (its starter no longer exists, or it started before generations stored one) calls no tool: each call is refused with 409 WORK_AUTHORITY_MISSING.

Passing wait=true holds the request open and returns the finished result instead. Streaming (stream: true) implies waiting, and cannot be combined with the background mode.

Reading a run back, step by step​

GET /v1/projects/{project_id}/generations/{generation_id}/transcript returns the turn as an ordered sequence of steps — what the model was asked, each step's tool calls and their results, and how it ended. It is the answer to "why did the agent do that", and it is the natural companion to a failed status. Debug a failed run uses it to name the tool call that broke a run whose status still reads completed. A run still running returns the steps it has ended so far and its in-flight tool calls.

Following a run as it runs​

GET /v1/projects/{project_id}/generations/{generation_id}/events returns the run's progress rows in seq order after after_seq: when each step and tool call starts and ends, and each ended step's content. The content needs traces:GetTrace on the run's trace and is refused with 403 without it; progress_only=true returns the rows alone (step null). stream=true answers Server-Sent Events instead, one event: progress frame per row, ending with data: [DONE] when the run settles. No row carries the vendor bag, streamed or not (Response messages).

Filtering the log​

GET /v1/projects/{project_id}/generations filters by agent, trace and status, so "every failed run of this agent" is one call. Roll out an agent version filters by agent to see which version served each run.

It also filters by orchestration_run_id and node_id, which is how an orchestration run is traced back to what its agent nodes actually generated: a node execution record carries no generation id, so the pointer lives on the generation. A node that was retried returns one generation per node_attempt.

Filtering by chain_id is how a continuation chain is expanded into its members — the chain record itself carries only their count.

session_id and actor_id narrow the same way: the turns behind one conversation, or every run one end user started across every session they appear in. Either naming nothing in the project yields an empty page rather than the unfiltered log. A session's own cost is read directly off GET /v1/projects/{project_id}/sessions/{session_id} — these filters are for the runs behind that figure.

Continuation chains​

A requires_action resumption, and a react approval expiry, each start a new generation rather than mutating the one that paused — but both stay part of the same continuation chain as the generation they continue. Every member shares one chain_id; a generation outside any chain has it null. Gate a tool with guardrails finds the continuation an approval starts.

An agent's max_chain_generations stop condition bounds a chain's length below the deployment's own ceiling. Reaching it ends the chain with stop_reason: "chain_limit", and files a matching chain_limit exception.

Purging content​

DELETE /v1/projects/{project_id}/generations/{generation_id}/content clears the run's content — metadata, error, extraction, and the internal recovery state of a paused run — and stamps content_redacted_at together with the principal that did it. The usage and cost records survive: what was spent stays auditable after what was said is gone. To stop content being recorded in the first place, set trace_content_mode on the agent; Run a zero-retention agent shows the usage that survives.

Purging the trace instead — DELETE /v1/projects/{project_id}/traces/{trace_id}/content — erases the steps object this generation's content lives in and cascades to every generation under it, so that is the call to reach for when a whole run must go.

Response messages​

output.response_messages carries the full message list the model produced — tool calls, tool results, and the final text — as the shape the underlying SDK returns it in.

No response carries providerOptions, the SDK's per-vendor bag, for any provider: the vendor state a replay needs is stored apart and never served. Its keys would name the vendor serving the request, which a naturali-managed provider keeps out of view.

Provider errors​

A generation that fails at the model provider records AI_PROVIDER_ERROR. On a provider with your own credentials, error.meta also carries provider_status_code and provider_response_body, the vendor's own status and answer, and error.message carries the vendor's wording. On the shared naturali provider the vendor's status, answer and wording are withheld, with the status and code unchanged: in the error a request answers, in every record and webhook that stores one, and in a streamed generation's error frame.

A generation is one node of a run

trace_id is the trace this generation belongs to: fetch its tree to see the sub-agent calls around it, and this generation's transcript to see what it did.

Examples​

Poll a background generation​

naturali get-generation \
--project-id proj_V1StGXR8Z5jdHi6B \
--generation-id gen_V1StGXR8Z5jdHi6B

List an agent's failed runs​

naturali list-generations \
--project-id proj_V1StGXR8Z5jdHi6B \
--agent-id agent_V1StGXR8Z5jdHi6B \
--status failed

Read the transcript of one run​

naturali get-generation-transcript \
--project-id proj_V1StGXR8Z5jdHi6B \
--generation-id gen_V1StGXR8Z5jdHi6B

Purge a run's content​

naturali purge-generation-content \
--project-id proj_V1StGXR8Z5jdHi6B \
--generation-id gen_V1StGXR8Z5jdHi6B