Traces API
API Reference
Traces API
Audit trail and debugging for all agent operations
GET
Traces API
Documentation Index
Fetch the complete documentation index at: https://docs.statebase.org/llms.txt
Use this file to discover all available pages before exploring further.
Traces API
Traces provide a complete audit trail of every operation in StateBase. Use traces for debugging, compliance, analytics, and understanding agent behavior.What Gets Traced?
Every API operation creates a trace:| 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 |
List Traces
GET /v1/traces
Lists all traces with optional filtering.
Query Parameters
| 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 |
Response
| Field | Type | Description |
|---|---|---|
data | array | Array of trace objects |
has_more | boolean | Whether more results exist |
Trace Object
| 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 |
Example
Get Trace
GET /v1/traces/{trace_id}
Retrieves a specific trace by ID.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
trace_id | string | ✅ Yes | Trace ID |
Example
Trace Actions Reference
Session Actions
| 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 |
State Actions
| Action | Description | Details Fields |
|---|---|---|
state.updated | State changed | reasoning, state_diff, version |
state.rolled_back | State reverted | from_version, to_version, reason |
Turn Actions
| Action | Description | Details Fields |
|---|---|---|
turn.added | Conversation turn logged | turn_number, input_type, output_type, reasoning |
Memory Actions
| 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 |
Common Use Cases
1. Debugging Production Issues
2. Audit Trail for Compliance
3. Performance Monitoring
4. Root Cause Analysis
5. Rollback Frequency Analysis
Filtering by Time Range
Get traces within a specific time window:Exporting Traces
Export traces for external analysis:Best Practices
✅ Do This
- Use traces for debugging (not just logging)
- Set up alerts on critical actions (rollbacks, errors)
- Export traces for long-term storage (compliance)
- Filter by time range (don’t fetch everything)
- Include reasoning in all operations (shows up in traces)
❌ Avoid This
- Don’t ignore rollback patterns (they indicate issues)
- Don’t fetch traces without filters (use pagination)
- Don’t store sensitive data in trace details
- Don’t delete traces (they’re your audit trail)
Retention Policy
| Tier | Trace Retention |
|---|---|
| Free | 7 days |
| Pro | 90 days |
| Enterprise | Custom (up to 7 years) |
Webhooks
Subscribe to trace events in real-time:| Event | Description |
|---|---|
trace.created | New trace logged |
trace.rollback | State rollback occurred |
trace.error | Error trace logged |
Error Responses
| 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 |
Next Steps
- Sessions API: Manage sessions
- Turns API: Log conversations
- Replay & Audit: Debugging strategies
Key Takeaway: Traces are your black box recorder. When things go wrong, traces tell you exactly what happened and why.