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
| Field | Type | Description |
|---|---|---|
id | string | Public ID of the trace |
project_id | string | Public ID of the project |
agent_id | string | Public ID of the agent that produced this trace |
file_id | string, nullable | Public 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_count | integer | Number of steps recorded in this trace |
parent_trace_id | string, nullable | Public 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_id | string, nullable | Public ID of the root trace for the entire execution tree. Null if this trace is itself the root. |
error | object, nullable | Why a generation in this trace failed (e.g. an upstream AI provider error). Null if no failure has been recorded. |
content_redacted_at | string (date-time), nullable | When 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_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) |
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:
| Field | Type | Description |
|---|---|---|
id | string | Public ID of the trace |
project_id | string | |
agent_id | string | |
file_id | string, nullable | |
step_count | integer | |
parent_trace_id | string, nullable | |
root_trace_id | string, nullable | |
error | object, nullable | Why a generation in this trace failed |
created_at | string (date-time) | |
content_redacted_at | string (date-time), nullable | When 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_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. |
children | object[] | 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.
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
- CLI
- SDK
- curl
naturali list-traces \
--project-id proj_V1StGXR8Z5jdHi6B \
--limit 20
const { data: traces } = await naturali.traces.listTraces({
path: { project_id: 'proj_V1StGXR8Z5jdHi6B' },
query: { limit: 20 },
});
curl "https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/traces?limit=20" \
-H "Authorization: Bearer $NATURALI_TOKEN"
Get one trace
- CLI
- SDK
- curl
naturali get-trace \
--project-id proj_V1StGXR8Z5jdHi6B \
--trace-id trace_V1StGXR8Z5jdHi6B
const { data: trace } = await naturali.traces.getTrace({
path: {
project_id: 'proj_V1StGXR8Z5jdHi6B',
trace_id: 'trace_V1StGXR8Z5jdHi6B',
},
});
curl https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/traces/trace_V1StGXR8Z5jdHi6B \
-H "Authorization: Bearer $NATURALI_TOKEN"
Read a whole run, then one node's generations
- CLI
- SDK
- curl
naturali get-trace-tree \
--project-id proj_V1StGXR8Z5jdHi6B \
--trace-id trace_V1StGXR8Z5jdHi6B
naturali list-generations \
--project-id proj_V1StGXR8Z5jdHi6B \
--trace-id trace_V1StGXR8Z5jdHi6B
const { data: tree } = await naturali.traces.getTraceTree({
path: {
project_id: 'proj_V1StGXR8Z5jdHi6B',
trace_id: 'trace_V1StGXR8Z5jdHi6B',
},
});
for (const child of tree?.children ?? []) {
const { data: generations } = await naturali.generations.listGenerations({
path: { project_id: 'proj_V1StGXR8Z5jdHi6B' },
query: { trace_id: child.id },
});
console.log(child.agent_id, generations?.data.length);
}
curl https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/traces/trace_V1StGXR8Z5jdHi6B/tree \
-H "Authorization: Bearer $NATURALI_TOKEN"
curl "https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/generations?trace_id=trace_V1StGXR8Z5jdHi6B" \
-H "Authorization: Bearer $NATURALI_TOKEN"
Purge a run's content
- CLI
- SDK
- curl
naturali purge-trace-content \
--project-id proj_V1StGXR8Z5jdHi6B \
--trace-id trace_V1StGXR8Z5jdHi6B
const { data: skeleton } = await naturali.traces.purgeTraceContent({
path: {
project_id: 'proj_V1StGXR8Z5jdHi6B',
trace_id: 'trace_V1StGXR8Z5jdHi6B',
},
});
console.log(skeleton?.content_redacted_at);
curl -X DELETE https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/traces/trace_V1StGXR8Z5jdHi6B/content \
-H "Authorization: Bearer $NATURALI_TOKEN"