Traces API
The Traces API lets you read your agents' execution traces programmatically — list recent runs and fetch a single run in detail, including the model, latency, input/output, intermediate steps, and user reactions. Use it to debug agent behavior or to feed traces into your own analysis and improvement pipelines.
Authenticate with a bearer API key from the Runbear Manage API Keys menu. Full request/response schemas live in the OpenAPI reference; MCP clients can read the same data through the MCP server's list_recent_agent_traces and get_agent_trace tools.
Endpoints
| Endpoint | Purpose |
|---|---|
GET /v1/agents/{agentId}/traces | List recent traces for an agent |
GET /v1/agents/{agentId}/traces/{traceId} | Read a single trace in detail |
GET /v1/agents/{agentId}/messages/{messageId}/trace | Resolve the trace behind a specific message |
Traces are retained for 90 days. The list endpoint is rate-limited to 30 requests per minute per organization — every response carries RateLimit-* headers, and a 429 includes Retry-After.
Session-start hook outcome
For organizations with the session-start hook feature enabled, the trace detail response includes a sessionStartHook field with the outcome of the hook for the trace's thread. The hook runs at most once per thread, so every trace in the same thread reports the same object; the field is null when the agent has no hook or the hook never ran for the thread.
{
"sessionStartHook": {
"fetchedAt": "2026-07-22T19:03:58.412Z",
"status": "ok",
"contexts": [
{ "name": "Session Context", "context": "tier: enterprise" }
]
}
}| Field | Meaning |
|---|---|
fetchedAt | ISO 8601 timestamp of when the hook was attempted |
status | ok — the hook completed successfully. degraded — the hook failed (timeout, error, or invalid response) and the session proceeded without injected context |
contexts | Context entries injected into the system prompt, one per result the hook returned |
Note that ok does not guarantee context was injected: a hook tool that returns no content is a successful no-op, reported as ok with an empty contexts array. When status is degraded, contexts is always empty.
Feature availability
The session-start hook is not generally available yet. Organizations without the feature do not see the sessionStartHook field in their responses at all.