---
title: "List agent traces"
method: GET
path: "/v1/agents/{id}/traces"
---

# List agent traces

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

## Request

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

List traces for a specific agent. Returns trace summaries including input/output content.

**Rate limit:** 30 requests per minute per organization. Every response carries the standard `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` (seconds until the window resets) headers; a `429` response additionally carries `Retry-After`. The limit is enforced per API replica, so the effective budget scales with the number of replicas — treat the headers as a pacing signal rather than an exact global counter. For large exports, page with a small `limit`, back off on `429`, and stay within the 90-day retention window.

## Path parameters

- `id` string, uuid, required: The ID of the agent to retrieve

## Query parameters

- `page` integer: Page number, starts at 1
- `limit` integer: Number of items per page (max 100)
- `sessionId` string: Filter traces by session ID (channel thread ID)
- `fromTimestamp` string, date-time: Filter traces from this timestamp (ISO 8601). Defaults to 90 days ago.
- `toTimestamp` string, date-time: Filter traces up to this timestamp (ISO 8601). Defaults to now.

## Response `200`

Default Response

- ListAgentTracesResponse
  - `traces` object[], required: Array of trace summaries
    - `id` string, required: Trace ID
    - `timestamp` string, required: ISO 8601 timestamp
    - `sessionId` string, nullable, required: Session ID
    - `latency` number, nullable, required: Latency in seconds
    - `input` string, nullable, required: Last user message text
    - `output` string, nullable, required: Assistant output markdown
    - `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
  - `meta` object, required: Pagination metadata
    - `page` number, required: Current page number
    - `limit` number, required: Items per page
    - `totalItems` number, required: Total number of items
    - `totalPages` number, required: Total number of pages

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