Audit trail and debugging for all agent operations
| Operation | Trace Action | Information Logged |
|---|---|---|
| Create session | session.created | agent_id, user_id, initial_state |
| Update state | state.updated | reasoning, state_diff, version |
| Add turn | turn.added | input, output, reasoning, metadata |
| Add memory | memory.created | content, type, tags |
| Rollback | state.rolled_back | from_version, to_version, reason |
| Fork session | session.forked | source_session, fork_version |
| Delete session | session.deleted | session_id, reason |
GET /v1/traces
Lists all traces with optional filtering.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id | string | No | Filter by session |
user_id | string | No | Filter by user |
action | string | No | Filter by action type (e.g., "state.updated") |
created_after | string | No | ISO 8601 timestamp (only traces after this time) |
created_before | string | No | ISO 8601 timestamp (only traces before this time) |
limit | integer | No | Max results (default: 20, max: 100) |
starting_after | string | No | Trace ID for pagination |
| Field | Type | Description |
|---|---|---|
data | array | Array of trace objects |
has_more | boolean | Whether more results exist |
| Field | Type | Description |
|---|---|---|
id | string | Unique trace ID |
session_id | string | Associated session (if applicable) |
user_id | string | Associated user (if applicable) |
action | string | Action type (e.g., "state.updated") |
actor | string | Who performed the action (API key prefix) |
timestamp | string | ISO 8601 timestamp |
details | object | Action-specific details |
metadata | object | Custom metadata |
GET /v1/traces/{trace_id}
Retrieves a specific trace by ID.
| Parameter | Type | Required | Description |
|---|---|---|---|
trace_id | string | ✅ Yes | Trace ID |
| Action | Description | Details Fields |
|---|---|---|
session.created | New session created | agent_id, user_id, initial_state |
session.updated | Session metadata updated | metadata_diff, ttl_seconds |
session.deleted | Session deleted | reason, turn_count, memory_count |
session.forked | Session forked | source_session_id, fork_version |
session.expired | Session TTL expired | ttl_seconds, last_activity |
| Action | Description | Details Fields |
|---|---|---|
state.updated | State changed | reasoning, state_diff, version |
state.rolled_back | State reverted | from_version, to_version, reason |
| Action | Description | Details Fields |
|---|---|---|
turn.added | Conversation turn logged | turn_number, input_type, output_type, reasoning |
| Action | Description | Details Fields |
|---|---|---|
memory.created | Memory added | content_preview, type, tags, embedded |
memory.updated | Memory modified | content_changed, tags_changed |
memory.deleted | Memory removed | content_preview, reason |
| Tier | Trace Retention |
|---|---|
| Free | 7 days |
| Pro | 90 days |
| Enterprise | Custom (up to 7 years) |
| Event | Description |
|---|---|
trace.created | New trace logged |
trace.rollback | State rollback occurred |
trace.error | Error trace logged |
| Status Code | Error Code | Description |
|---|---|---|
| 400 | invalid_request | Invalid filter parameters |
| 404 | trace_not_found | Trace doesn’t exist or expired |
| 429 | rate_limit_exceeded | Too many requests |