---
title: "List Traces"
method: GET
path: "/traces"
tags: ["Traces", "Traces"]
---

# List Traces

`GET /traces`

Retrieve a paginated list of execution traces with optional filtering.

**Traces provide observability into:**
- Agent execution flows
- Model invocations and token usage
- Tool calls and their results
- Errors and performance bottlenecks

**Filtering Options:**
- By run, session, user, or agent ID
- By status (OK, ERROR)
- By time range

**Pagination:**
- Use `page` (1-indexed) and `limit` parameters
- Response includes pagination metadata (total_pages, total_count, etc.)

**Response Format:**
Returns summary information for each trace. Use GET `/traces/{trace_id}` for detailed hierarchy.

## Query parameters

- `run_id` string, nullable — Filter by run ID
- `session_id` string, nullable — Filter by session ID
- `user_id` string, nullable — Filter by user ID
- `agent_id` string, nullable — Filter by agent ID
- `team_id` string, nullable — Filter by team ID
- `workflow_id` string, nullable — Filter by workflow ID
- `status` string, nullable — Filter by status (OK, ERROR)
- `start_time` string, nullable — Filter traces starting after this time (ISO 8601 format with timezone, e.g., '2025-11-19T10:00:00Z' or '2025-11-19T15:30:00+05:30'). Times are converted to UTC for comparison.
- `end_time` string, nullable — Filter traces ending before this time (ISO 8601 format with timezone, e.g., '2025-11-19T11:00:00Z' or '2025-11-19T16:30:00+05:30'). Times are converted to UTC for comparison.
- `page` integer — Page number (1-indexed)
- `limit` integer — Number of traces per page
- `db_id` string, nullable — Database ID to query traces from

## Response `200`

List of traces retrieved successfully

- PaginatedResponseTraceSummary
  - `data` TraceSummary[], required — List of items for the current page
    - `trace_id` string, required — Unique trace identifier
    - `name` string, required — Trace name (usually root span name)
    - `status` string, required — Overall status (OK, ERROR, UNSET)
    - `duration` string, required — Human-readable total duration
    - `start_time` string, date-time, required — Trace start time (Pydantic auto-serializes to ISO 8601)
    - `end_time` string, date-time, required — Trace end time (Pydantic auto-serializes to ISO 8601)
    - `total_spans` integer, required — Total number of spans in this trace
    - `error_count` integer, required — Number of spans with errors
    - `input` string, nullable — Input to the agent
    - `run_id` string, nullable — Associated run ID
    - `session_id` string, nullable — Associated session ID
    - `user_id` string, nullable — Associated user ID
    - `agent_id` string, nullable — Associated agent ID
    - `team_id` string, nullable — Associated team ID
    - `workflow_id` string, nullable — Associated workflow ID
    - `created_at` string, date-time, required — Time when trace was created (Pydantic auto-serializes to ISO 8601)
  - `meta` PaginationInfo, required
    - `page` integer — Current page number (0-indexed)
    - `limit` integer — Number of items per page
    - `total_pages` integer — Total number of pages
    - `total_count` integer — Total count of items
    - `search_time_ms` number — Search execution time in milliseconds

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `404` — Not Found
- `422` — Validation Error
- `500` — Internal Server Error

---

[API](https://skmtc.net/agno/apis/agno-api-reference.md) · [All operations](https://skmtc.net/agno/apis/agno-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/agno/agno-api-reference/revisions/5f6149d395d0/schema)