---
title: "Retrieve agent trace"
method: GET
path: "/v1/agents/{id}/traces/{traceId}"
---

# Retrieve agent trace

`GET /v1/agents/{id}/traces/{traceId}`

## Request

- Base URL: `https://api.runbear.io`
- URL: `https://api.runbear.io/v1/agents/{id}/traces/{traceId}`
- Auth: HTTP bearer

Retrieve detailed trace data for a specific agent trace, including messages and generation output.

## Path parameters

- `id` string, uuid, required: The ID of the agent
- `traceId` string, required: The ID of the trace

## Response `200`

Default Response

- RetrieveAgentTraceResponse
  - `traceId` string, required: Trace ID
  - `timestamp` string, required: ISO 8601 timestamp
  - `threadId` string, nullable, required: Thread ID (UUID)
  - `latency` number, nullable, required: Latency in seconds
  - `metadata` object, required: Trace metadata (sensitive fields excluded)
  - `model` string, nullable, required: LLM model used in the last generation
  - `input` unknown
  - `steps` object[], required: Interaction steps including tool calls from this turn
    - `role` string, required: Message role
    - `content` unknown
  - `output` unknown
  - `reactions` object[], required: Emoji reactions on this trace's bot response
    - `emoji` string, required: Emoji name (skin tone variants merged)
    - `count` integer, required: Number of unique users who reacted
  - `userContext` object: User context metadata passed via SDK
  - `sessionStartHook` object, nullable: Outcome of the agent's session-start hook for this trace's thread. The hook runs at most once per thread, so every trace in the same thread carries the same value. Absent entirely for organizations without the session-start hook feature. For organizations that have it, `null` means the agent has no session-start hook configured, or the hook never ran for this thread.
    - `fetchedAt` string, required: ISO 8601 timestamp of when the hook was attempted
    - `status` 'ok' | 'degraded', required: `ok` — the hook completed successfully; its returned context entries (possibly none) were injected into the system prompt. `degraded` — the hook failed (timeout, error, or invalid response) and the session proceeded without injected context.
    - `contexts` object[], required: Context entries injected into the system prompt, one per result the hook returned. May be empty when `status` is `ok` (the hook returned no content) and is always empty when `status` is `degraded`.
      - `name` string, required: Name of the context entry
      - `context` string, required: Context text injected into the system prompt

## Other responses

- `403`: The agent runs in HIPAA data handling mode and Runbear's protected trace store is not enabled. Terminal until the agent's data handling mode changes or Runbear enables the store.

---

[API](https://skmtc.dev/runbear/apis/runbear-api.md) - [All operations](https://skmtc.dev/runbear/apis/runbear-api/llms.txt) - [OpenAPI document](https://skmtc.dev/runbear/apis/runbear-api/revisions/c6a9c3066a5a?raw)