Traces

Get trace tree

Returns the full execution tree rooted at the given trace (or its root if the given trace is a child). Each node represents one agent's execution session. The children array contains traces triggered by sub-agent tool calls from that trace. A node's generations are listed by GET /v1/projects/{project_id}/generations?trace_id=, and a node's direct children page by GET /v1/projects/{project_id}/traces?parent_trace_id=.

get/v1/projects/{project_id}/traces/{trace_id}/tree

Request

  • Base URL: https://api.naturali.ai
  • URL: https://api.naturali.ai/v1/projects/{project_id}/traces/{trace_id}/tree
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://api.naturali.ai/authorize, token URL https://api.naturali.ai/token, scopes: mcp:access)

Path parameters

trace_idstring required

Public ID of any trace in the tree (root or child)

Response

Trace tree rooted at the resolved root trace

idstring

Public ID of the trace

project_idstring
agent_idstring
file_idstring nullable
step_countinteger
parent_trace_idstring nullable
root_trace_idstring nullable
created_atstring date-time
content_redacted_atstring 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'user' | 'api_key' | 'agent' | 'automation' | 'approval' | 'system'

What kind of principal acted. user and api_key are authenticated callers, and the id is the user's (user_…) or the key's own (key_…), so a record names which key acted rather than its owner. agent is an agent writing under its own identity (agent_…). automation is the task engine acting on a dispatch outcome and approval an approval resolution; neither carries an id. system is the platform itself, with an id naming the mechanism (retention_sweep, zero_retention).

content_redacted_by_principal_idstring 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.

childrenTraceTreeNode[] circular

Example response

{
  "error": {
    "code": "AI_PROVIDER_ERROR",
    "message": "Provider returned 402: insufficient credits"
  },
  "content_redacted_by_principal_type": "user",
  "content_redacted_by_principal_id": "user_V1StGXR8Z5jdHi6B"
}

Changes

No recorded changes to this operation across all 1 revision of this API.