List Runs

GEThttps://api.boringmarketing.com/brands/{brand_id}/runs

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

Path parameters

brand_idstringrequired

The brand UUID.

Response

{
  "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`

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.

Example

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