> For the complete documentation index, see [llms.txt](/llms.txt).
> A full single-fetch corpus is available at [llms-full.txt](/llms-full.txt).
---
title: "Runs & Traces"
description: "List workflow runs, read a run's logs, and fetch the distributed trace recorded for each run."
last_verified: 2026-07-27
---


**Endpoints**: `GET /api/v1/analytics/runs`, `GET /api/v1/analytics/runs/:run_id`, `GET /api/v1/runs/:runId/logs`, `GET /api/v1/traces`, `GET /api/v1/traces/:traceId`
**Auth**: `X-API-KEY` or `Authorization: Bearer <token>` (required)
**Error envelope**: these endpoints return `{"error": string, "message": string}` on failure — no `code` or `success` field, unlike the rest of the API


A **run** is a single execution of a workflow. A **trace** is the recorded execution path of that run — its steps, retries, and timing — captured by AGNT5's OpenTelemetry pipeline.

> **Note:** These observability endpoints predate the shared `{success, message, data}` envelope described in [Authentication](/docs/api-reference/authentication.md). Successful list responses here return a bare array or a plain `{items, count, ...}` object, and errors return `{"error": string, "message": string}` with no `code` field.

## Next steps

* [Deployments](/docs/api-reference/deployments.md): the deployment a run's worker belonged to
* [Workers](/docs/api-reference/workers.md): the process that executed a run
* [Operating deployments](/docs/run/overview.md): where traces surface in Studio alongside logs and metrics