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


**Gateway endpoints** (`https://gw.agnt5.com`, service key): `POST /v1/{type}/{name}/run|submit|stream|batch`, `GET /v1/runs`, `GET /v1/runs/{run_id}`, `GET /v1/runs/{run_id}/output`, `GET /v1/runs/{run_id}/events` (SSE), `POST /v1/runs/{run_id}/cancel`, `POST /v1/workflows/resume/{run_id}`
**Control plane 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 function, workflow, tool, or agent. A **trace** is the recorded execution path of that run — its steps, retries, and timing — captured by AGNT5's OpenTelemetry pipeline.

These endpoints come from two APIs:

* **Gateway** (`https://gw.agnt5.com`, a [service key](/docs/build/local-development.md#create-a-service-key) in `X-API-KEY`): start runs, list and read runs, fetch output, follow events, cancel, and resume paused workflows. These are the endpoints labeled *Gateway* in the sidebar.
* **Control plane** (`https://api.agnt5.com`, a personal API key or bearer token): run analytics, logs, and traces.

See [Authentication](/docs/api-reference/authentication.md) for both credentials.

> **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