# Traces API (/api-reference/traces)



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](https://api.runbear.io/v1/docs); MCP clients can read the same data through the [MCP server](./mcp-server)'s `list_recent_agent_traces` and `get_agent_trace` tools.

## Endpoints [#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 [#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.

```json
{
  "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.

<Callout type="info" title="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.
</Callout>