Traces

Get a trace

Returns a single trace by ID.

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

Request

  • Base URL: https://api.naturali.ai
  • URL: https://api.naturali.ai/v1/projects/{project_id}/traces/{trace_id}
  • 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 the trace

Response

Trace details

idstring

Public ID of the trace

project_idstring

Public ID of the project

agent_idstring

Public ID of the agent that produced this trace

file_idstring 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_countinteger

Number of steps recorded in this trace

parent_trace_idstring 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_idstring nullable

Public ID of the root trace for the entire execution tree. Null if this trace is itself the root.

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.

created_atstring date-time

Example response

{
  "id": "trace_V1StGXR8Z5jdHi6B",
  "file_id": "file_xyz789",
  "step_count": 2,
  "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.