---
title: "Retrieve the trace for a message"
method: GET
path: "/v1/agents/{id}/messages/{messageId}/trace"
---

# Retrieve the trace for a message

`GET /v1/agents/{id}/messages/{messageId}/trace`

## Request

- Base URL: `https://api.runbear.io`
- URL: `https://api.runbear.io/v1/agents/{id}/messages/{messageId}/trace`
- Auth: HTTP bearer

Resolve and retrieve the trace produced for a specific message, identified by the message ID returned from the thread messages endpoint. Returns the same shape as retrieveAgentTrace. Returns 404 when no trace can be resolved for the message — because it predates the trace-retention window, because the message belongs to a different agent than the one in the path, or because the message was not produced by an agent run at all. A non-UUID message ID is rejected at validation with a 400.

**Rate limit:** shares the trace-list limiter — 30 requests per minute per organization. Responses carry `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` headers, plus `Retry-After` on a `429`.

## Path parameters

- `id` string, uuid, required: The ID of the agent
- `messageId` string, uuid, required: The ID of the message (as returned by the thread messages endpoint) to resolve a trace for

## 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.
- `429`: Rate limit exceeded — either the per-org trace-list limiter or a sustained upstream throttle. Retry after the number of seconds in the `Retry-After` header.

---

[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)