---
title: List Runs
api: GET /brands/{brand_id}/runs
description: "List all pipeline runs for a brand, with status and stage information."
---

> **For AI agents:** the complete documentation index is at [llms.txt](https://docs.boringmarketing.com/llms.txt). Append `.md` to any page URL for its markdown version.

Returns all pipeline runs for a brand, ordered by creation time (newest first).

## Path parameters

<ParamField path="brand_id" type="string" required>
  The brand UUID.
</ParamField>

## Response

```json
{
  "brand_id": "brand-uuid",
  "total": 3,
  "runs": [
    {
      "id": "run-uuid-1",
      "brand_id": "brand-uuid",
      "kind": "full",
      "status": "done",
      "error": null,
      "started_at": "2026-04-07T10:00:00Z",
      "finished_at": "2026-04-07T10:28:00Z",
      "meta": {
        "current_stage": "queue_building"
      }
    },
    {
      "id": "run-uuid-2",
      "brand_id": "brand-uuid",
      "kind": "full",
      "status": "running",
      "error": null,
      "started_at": "2026-04-07T11:00:00Z",
      "finished_at": null,
      "meta": {
        "current_stage": "evidence_collection",
        "stage_detail": "collecting evidence for 12 families (concurrency=5)",
        "stage_started_at": "2026-04-07T11:00:12Z"
      }
    }
  ]
}
```

## Run object fields

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Run UUID |
| `brand_id` | string | Brand UUID |
| `kind` | string | Type of run — see table below |
| `status` | string | `queued`, `running`, `done`, or `failed` |
| `error` | string \| null | Error message if `status=failed` |
| `started_at` | string (ISO 8601) | When the run was accepted |
| `finished_at` | string \| null | When the run reached a terminal state |
| `meta` | object | Additional run metadata — see below |

Stage progress lives inside `meta`:

| `meta` field | Description |
|--------------|-------------|
| `meta.current_stage` | Current pipeline stage string (see `kind` column for which runs emit stages) |
| `meta.stage_detail` | Human-readable detail for the current stage |
| `meta.stage_started_at` | When the current stage began |

## Run kinds

| Kind | Triggered by |
|------|-------------|
| `full` | `POST /brands/{id}/analyze` |
| `brand_enrichment` | `POST /brands/{id}/enrich/brand` |
| `technical_enrichment` | `POST /brands/{id}/enrich/technical` |
| `llm_enrichment` | `POST /brands/{id}/enrich/llm` |
| `discovery` | `POST /brands/{id}/discover` |
| `competitor_discovery` | `POST /brands/{id}/discover-competitors` |
| `synthesize` | `POST /brands/{id}/synthesize` |
| `scoring` | `POST /brands/{id}/score` |
| `brief` | `POST /brands/{id}/brief` |
| `execution` | `POST /brands/{id}/execute` |

<Warning>
**Only `full` runs emit `meta.current_stage`.** Every other run kind — `brand_enrichment`, `technical_enrichment`, `llm_enrichment`, `discovery`, `competitor_discovery`, `synthesize`, `scoring`, `brief`, `execution` — runs with `meta.current_stage = null` for the entire lifetime of the run. Use `status` to know whether they finished, not `current_stage`. The `competitor_discovery` stage on `full` runs is itself only emitted when the brand has no competitors set; otherwise it is skipped silently.
</Warning>

## Example

```bash
curl -H "X-API-Key: $BM_API_KEY" \
  https://api.boringmarketing.com/brands/$BRAND_ID/runs
```