Skip to main content

Traces

The execution record of a run — one node per agent session, nested by sub-agent call, and the control that erases its content.

Overview​

A trace is created for you whenever an agent runs. One trace covers one agent's execution session; when that agent calls another agent as a tool, the callee gets its own trace with parent_trace_id pointing back, so a multi-agent run is a tree rather than a flat log. Every generation carries the trace_id it belongs to.

Two reads and one erasure, which is the whole surface: list or get a trace, fetch the tree rooted above it (optionally with each node's generations embedded), and purge a run's content while leaving its audit skeleton behind.

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 → Traces.

Data Model​

Trace​

FieldTypeDescription
idstringPublic ID of the trace
project_idstringPublic ID of the project
agent_idstringPublic ID of the agent that produced this trace
file_idstring, nullablePublic ID of the File containing the full serialized steps JSON. Null if the trace has not been saved yet (save is fire-and-forget).
step_countintegerNumber of steps recorded in this trace
parent_trace_idstring, nullablePublic ID of the parent trace. Null if this trace is the root (i.e., it was not triggered by a sub-agent call from another trace).
root_trace_idstring, nullablePublic ID of the root trace for the entire execution tree. Null if this trace is itself the root.
errorobject, nullableWhy a generation in this trace failed (e.g. an upstream AI provider error). Null if no failure has been recorded.
content_redacted_atstring (date-time), nullableWhen the trace's content was purged. Non-null means the steps object has been deleted from storage and the content columns cleared, while this row survives as an auditable skeleton (ids, timestamps, step count). A purged trace still reads back as a skeleton with this marker set rather than as a 404, so the erasure is provable.
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)

For key auth, content_redacted_by_principal_id is the id of the project's key the request ran on, not the key the caller sent.

TraceTreeNode​

The tree response is a Trace plus one extra:

FieldTypeDescription
idstringPublic ID of the trace
project_idstring
agent_idstring
file_idstring, nullable
step_countinteger
parent_trace_idstring, nullable
root_trace_idstring, nullable
errorobject, nullableWhy a generation in this trace failed
created_atstring (date-time)
content_redacted_atstring (date-time), nullableWhen the trace's content was purged. Non-null means the steps object has been deleted from storage and the content columns cleared, while this row survives as an auditable skeleton (ids, timestamps, step count). A purged trace still reads back as a skeleton with this marker set rather than as a 404, so the erasure is provable.
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.
childrenobject[]Child traces triggered by sub-agent calls from this trace

Key Concepts​

Reading a multi-agent run​

GET /v1/projects/{project_id}/traces/{trace_id}/tree takes any trace in a tree — root or child — resolves the root, and returns the whole tree from there. So "show me this run" needs one call and the id you happen to be holding, not a walk up parent_trace_id. Debug a failed run starts there when a sub-agent stops on an error.

A node's generations are a paged list: GET /v1/projects/{project_id}/generations with trace_id set to the node's id. Each generation's id is what GET /v1/projects/{project_id}/generations/{generation_id}/transcript reads step by step. A node's direct children alone are GET /v1/projects/{project_id}/traces with parent_trace_id.

Purging a run's content​

DELETE /v1/projects/{project_id}/traces/{trace_id}/content deletes the steps object and clears the content fields, cascading to every descendant trace and to all of their generations. The cascade is the point: a descendant holds its own steps object covering the same run, so erasing only the trace you asked about would leave the content readable one level down.

What survives is an auditable skeleton — ids, timestamps, step counts, and the generations' usage attribution — stamped with content_redacted_at and the principal that acted. A purged trace therefore reads back as a skeleton rather than a 404: the erasure is provable, which a missing row would not be. The call is idempotent, and it keeps the original content_redacted_at on a second purge.

Two related controls live on the project: a retention window purges content past it on a daily sweep, and trace_content_mode: none — also settable per agent — never writes content at all, which is the stronger guarantee. Run a zero-retention agent reads back the skeleton such a run leaves.

Who may do what​

Every route needs any project member.

Reading the steps object directly

file_id names the stored file holding the serialized steps, so GET /v1/projects/{project_id}/files/{file_id}/download will fetch it. It is the raw serialization, not a documented format — read a run through the tree and each generation's transcript when you want the contract, and reach for the object only when you need what it happens to contain.

Examples​

List the project's traces​

naturali list-traces \
--project-id proj_V1StGXR8Z5jdHi6B \
--limit 20

Get one trace​

naturali get-trace \
--project-id proj_V1StGXR8Z5jdHi6B \
--trace-id trace_V1StGXR8Z5jdHi6B

Read a whole run, then one node's generations​

naturali get-trace-tree \
--project-id proj_V1StGXR8Z5jdHi6B \
--trace-id trace_V1StGXR8Z5jdHi6B

naturali list-generations \
--project-id proj_V1StGXR8Z5jdHi6B \
--trace-id trace_V1StGXR8Z5jdHi6B

Purge a run's content​

naturali purge-trace-content \
--project-id proj_V1StGXR8Z5jdHi6B \
--trace-id trace_V1StGXR8Z5jdHi6B