Skip to main content
The Trace APIs enable you to retrieve, filter, analyze, and export execution traces for agent sessions. These APIs help developers inspect runtime behavior, debug workflows, analyze performance, and integrate traces with external observability systems.

​
Base URL

/api/projects/:projectId/sessions

​
Authentication

All APIs require bearer token authentication. Authorization: Bearer <TOKEN>

​
Get Session Traces

Retrieve the complete set of traces for a session. Endpoint:GET /api/projects/:projectId/sessions/:sessionId/traces Example Request 
curl -X GET /api/projects/:projectId/sessions/:sessionId/traces \
  -H "Authorization: Bearer $TOKEN"
Response Returns all trace events associated with the specified session. Trace Event Types The following event types can be retrieved and filtered. Use query parameters to narrow down trace results.
Event TypeDescription
llm_callLLM API call details including model, tokens, latency, and prompts
tool_callTool invocation with parameters
tool_resultTool execution response
decisionRouting or workflow decisions
handoffTransfer between agents
guardrail_evalGuardrail evaluation results
state_changeSession state or variable updates
errorRuntime or execution errors
responseFinal agent response

​
Filter by Event Type

Retrieve traces for a specific event category. Endpoint : GET /api/projects/:projectId/sessions/:id/traces?eventType=decision Example 
curl -X GET \
"/api/projects/:projectId/sessions/:id/traces?eventType=decision" \
-H "Authorization: Bearer $TOKEN"

​
Filter by Decision Kind

Retrieve traces for a specific decision type. Endpoint: GET /api/projects/:projectId/sessions/:id/traces?decisionKind=handoff Example 
curl -X GET \
"/api/projects/:projectId/sessions/:id/traces?decisionKind=handoff" \
-H "Authorization: Bearer $TOKEN"

​
Retrieve Child Events for a Span

Get nested events associated with a specific span. Endpoint: GET /api/projects/:projectId/sessions/:id/traces/:spanId/children Example 
curl -X GET \
/api/projects/:projectId/sessions/:id/traces/:spanId/children \
-H "Authorization: Bearer $TOKEN"

​
Include Metrics in Trace Response

Include execution metrics along with trace events. Endpoint: GET /api/projects/:projectId/sessions/:id/traces?include=metrics Example 
curl -X GET \
"/api/projects/:projectId/sessions/:id/traces?include=metrics" \
-H "Authorization: Bearer $TOKEN"

​
View Aggregated Session Metrics

Retrieve performance metrics aggregated across the session. Endpoint: GET /api/projects/:projectId/sessions/:id/metrics Example Request 
curl -X GET /api/projects/:projectId/sessions/:id/metrics \
  -H "Authorization: Bearer $TOKEN"
Response Includes:
  • Total session latency
  • Per-turn latency breakdown
  • Token usage per LLM call
  • Tool call count
  • Tool success rate
  • Guardrail evaluation count
  • Guardrail block rate

​
Run Trace Analysis

Run automated diagnostics on session traces. Endpoint: GET /api/projects/:projectId/sessions/:id/analysis Example Request 
curl -X GET /api/projects/:projectId/sessions/:id/analysis \
  -H "Authorization: Bearer $TOKEN"
Response Includes:
  • Slow spans
  • Error patterns
  • Decision anomalies
  • Optimization suggestions

​
Export Traces

Export traces for offline analysis or integration with observability tools.

​
Export Traces as CSV

Endpoint: GET /api/projects/:projectId/sessions/export?format=csv Example Request 
curl -X GET \
"/api/projects/:projectId/sessions/export?format=csv" \
-H "Authorization: Bearer $TOKEN"

​
Export LLM Generations Across Sessions

Retrieve all LLM call events across sessions. Endpoint: GET /api/projects/:projectId/sessions/generations Example Request 
curl -X GET /api/projects/:projectId/sessions/generations \
  -H "Authorization: Bearer $TOKEN"
Response Returns LLM generation events across sessions, including:
  • Model usage
  • Token consumption
  • Latency
  • Prompt metadata