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

# Bulk-export agent traces

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

## Request

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

Export an agent's full interaction history — input, output, and tool calls for every turn — over a large time window, in cursor-paginated pages.

Use this instead of `listAgentTraces` for high-volume extraction: analytics pipelines, warehouse loads, and multi-month pulls. It reads a higher-throughput upstream API and carries a separate, larger rate-limit budget.

**Paging:** follow `meta.cursor` until it is `null`, passing it back as the `cursor` query parameter. Do not pass `fromTimestamp`/`toTimestamp` changes mid-export. Every page contains whole traces — a trace is never split across pages nor returned twice — so pages vary in size.

**Rate limit:** 20 requests per minute per organization, enforced per API replica. Responses carry `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset`; a `429` additionally carries `Retry-After`.

**Retention:** traces older than 90 days are not retained and cannot be exported; `fromTimestamp` is silently clamped to that window.

**Freshness:** a trace becomes exportable a few minutes after it completes (measured at ~2-3 minutes). An export whose `toTimestamp` reaches the present may therefore omit the most recent interactions; they appear on a later run. For a reproducible extract, set `toTimestamp` at least 15 minutes in the past.

## Path parameters

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

## Query parameters

- `fromTimestamp` string, date-time: Export traces from this timestamp (ISO 8601). Defaults to, and is clamped at, 90 days ago.
- `toTimestamp` string, date-time: Export traces up to this timestamp (ISO 8601, exclusive). Defaults to now. Ignored once `cursor` is supplied.
- `cursor` string: Continuation token from the previous page's `meta.cursor`. Pass it back verbatim; treat it as opaque.

## Response `200`

Default Response

- ExportAgentTracesResponse
  - `traces` ExportedTrace[], required: Whole traces, newest first. Page size varies because traces are never split across pages.
    - `traceId` string, required: Trace ID
    - `timestamp` string, required: ISO 8601 timestamp the interaction started
    - `sessionId` string, nullable, required: Session ID (channel thread ID)
    - `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
    - `output` unknown
    - `steps` object[], required: Interaction steps including tool calls from this turn
      - `role` string, required: Message role
      - `content` unknown
  - `meta` ExportTracesMeta, required
    - `cursor` string, nullable, required: Pass back as `cursor` to fetch the next page. `null` means the requested window has been fully exported.

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