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
| Field | Type | Description |
|---|---|---|
id | string | Public ID of the generation |
project_id | string | Public ID of the project |
agent_id | string | Public ID of the agent that ran this generation |
trace_id | string | Public ID of the trace this generation belongs to |
initiator_generation_id | string, nullable | Public 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_id | string, nullable | Public 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_id | string, nullable | Public 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_id | string, nullable | Public 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_id | string, nullable | Public 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_type | string, nullable | Who started the generation |
started_by_principal_id | string, nullable | Public id of that principal: the user (user_…), or for API key auth the key itself (key_…), so the record names which key acted. |
acted_as | object, nullable | The 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_for | object, nullable | The 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. |
status | running | requires_action | completed | failed | Lifecycle status of the generation |
started_at | string (date-time) | |
completed_at | string (date-time), nullable | When the generation reached a terminal state |
last_activity_at | string (date-time), nullable | |
stop_reason | string, nullable | Why 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. |
error | object, nullable | Why the generation failed: AI_PROVIDER_ERROR for an upstream provider failure, GENERATION_FAILED for any other failure of the turn. |
action_id | string, nullable | Logical action label supplied on the generate request. Recorded on the generation's usage event for per-action spend rollups. |
trigger_id | string, nullable | Trigger that initiated the generation, when applicable |
orchestration_run_id | string, nullable | Orchestration run that dispatched the generation. Null for a standalone generation. |
node_id | string, nullable | Node within orchestration_run_id that dispatched the generation. Together with the run it forms the usage event's replay identity. |
node_attempt | integer, nullable | The 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_version | integer, nullable | Agent config version that served this generation, resolved by the served-version resolver (see agent versions). |
source | string, nullable | What produced the generation besides production traffic: eval for an eval run, decider for a decider question. null for production traffic. |
extraction | object, nullable | What 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_surface | object, nullable | What 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. |
retrieval | object[], nullable | What 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_key | string, nullable | The 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. |
usage | object, nullable | What 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. |
routing | object, nullable | What the model route did for this generation. Present only when the agent resolves its model through a model_route_id. |
metadata | object | Caller-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_at | string (date-time), nullable | When 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_type | string, nullable | Who 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_id | string, nullable | Public 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_at | string (date-time) | |
updated_at | string (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— aclient-type tool is waiting on you; submit its output to resume the run.failed— readerror.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.
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
- CLI
- SDK
- curl
naturali get-generation \
--project-id proj_V1StGXR8Z5jdHi6B \
--generation-id gen_V1StGXR8Z5jdHi6B
const { data: generation } = await naturali.generations.getGeneration({
path: {
project_id: 'proj_V1StGXR8Z5jdHi6B',
generation_id: 'gen_V1StGXR8Z5jdHi6B',
},
});
curl https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/generations/gen_V1StGXR8Z5jdHi6B \
-H "Authorization: Bearer $NATURALI_TOKEN"
List an agent's failed runs
- CLI
- SDK
- curl
naturali list-generations \
--project-id proj_V1StGXR8Z5jdHi6B \
--agent-id agent_V1StGXR8Z5jdHi6B \
--status failed
const { data: failed } = await naturali.generations.listGenerations({
path: { project_id: 'proj_V1StGXR8Z5jdHi6B' },
query: { agent_id: 'agent_V1StGXR8Z5jdHi6B', status: 'failed' },
});
curl "https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/generations?agent_id=agent_V1StGXR8Z5jdHi6B&status=failed" \
-H "Authorization: Bearer $NATURALI_TOKEN"
Read the transcript of one run
- CLI
- SDK
- curl
naturali get-generation-transcript \
--project-id proj_V1StGXR8Z5jdHi6B \
--generation-id gen_V1StGXR8Z5jdHi6B
const { data: transcript } = await naturali.generations.getGenerationTranscript(
{
path: {
project_id: 'proj_V1StGXR8Z5jdHi6B',
generation_id: 'gen_V1StGXR8Z5jdHi6B',
},
}
);
curl https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/generations/gen_V1StGXR8Z5jdHi6B/transcript \
-H "Authorization: Bearer $NATURALI_TOKEN"
Purge a run's content
- CLI
- SDK
- curl
naturali purge-generation-content \
--project-id proj_V1StGXR8Z5jdHi6B \
--generation-id gen_V1StGXR8Z5jdHi6B
await naturali.generations.purgeGenerationContent({
path: {
project_id: 'proj_V1StGXR8Z5jdHi6B',
generation_id: 'gen_V1StGXR8Z5jdHi6B',
},
});
curl -X DELETE https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/generations/gen_V1StGXR8Z5jdHi6B/content \
-H "Authorization: Bearer $NATURALI_TOKEN"