Traces

Purge trace content

Deletes the trace's steps object from storage and clears its content columns (file_id, error), cascading to every descendant trace and to all of their generations. A descendant holds its own steps object covering the same run, so the cascade is what makes the erasure complete rather than merely partial.

The rows survive as auditable skeletons with content_redacted_at set — ids, timestamps, step counts, and the generations' usage-attribution fields are preserved, because the billing and audit ledger must outlive a tenant's erasure of the content. A purged trace therefore reads back as a skeleton, not a 404: a 404 would prove nothing.

Idempotent — purging an already-purged trace succeeds and leaves the original content_redacted_at in place.

delete/v1/projects/{project_id}/traces/{trace_id}/content

Request

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

The purged trace skeleton

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.