> ## Documentation Index
> Fetch the complete documentation index at: https://docs.briefedmedia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Running and polling

> Trigger a run, avoid double-spending, poll for results, and cancel.

# Running and polling

Only a published version runs. A workflow with no published version returns `404 no_published_version`.

## Start a run

```bash theme={null}
curl -X POST "$BRIEFED_API/api/v1/workflows/$WF/run" \
  -H "Authorization: Bearer $BRIEFED_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'
```

```json theme={null}
{ "ok": true, "runId": "...", "host": "workflow_run", "estimate": { "costMinorUnits": 450 } }
```

An optional `question` may be supplied (max 1000 characters). It is a label only. The pinned subjects carry identity, and the question never changes what the run is about.

Requires `write:workflows`.

## Idempotency

**Starting a run draws on your research usage allowance.** Send an `Idempotency-Key` on every run request. A retry carrying the same key returns the original result rather than starting, and charging for, a second run.

Without a key, a client that retries on a timeout spends twice. Treat the header as mandatory in any automated caller.

## Usage and capacity

If the allowance cannot be reserved, the run does not start:

```json theme={null}
{
  "error": "research_capacity_unavailable",
  "message": "Research capacity is unavailable for this run.",
  "details": { "reason": "..." }
}
```

`402` means the account's allowance for the period is exhausted. `503` means the usage system itself was unreachable (`details.reason` of `credit_policy_unconfigured` or `platform_unavailable`). Retry the `503`; the `402` will not clear until the allowance resets or the plan changes.

Check the weight before committing by validating the definition. The estimate returned there is the same figure the run reserves against.

## Poll a run

```bash theme={null}
curl "$BRIEFED_API/api/v1/workflows/$WF/runs/$RUN_ID" \
  -H "Authorization: Bearer $BRIEFED_KEY"
```

For a composition, the response expands the child runs and their per-node outputs, so you can see which step produced what rather than only the final state. Poll until the run reaches a terminal state.

## List runs

Per workflow:

```bash theme={null}
curl "$BRIEFED_API/api/v1/workflows/$WF/runs" -H "Authorization: Bearer $BRIEFED_KEY"
```

Across every workflow you own:

```bash theme={null}
curl "$BRIEFED_API/api/v1/workflows/runs?state=open" -H "Authorization: Bearer $BRIEFED_KEY"
```

`state` accepts `all` (default), `open` and `terminal`.

## Deliver and cancel

```bash theme={null}
curl -X POST "$BRIEFED_API/api/v1/workflows/$WF/runs/$RUN_ID/deliver" -H "Authorization: Bearer $BRIEFED_KEY"
curl -X POST "$BRIEFED_API/api/v1/workflows/$WF/runs/$RUN_ID/cancel"  -H "Authorization: Bearer $BRIEFED_KEY"
```

Both require `write:workflows`. Delivery is useful when a gate held a below-floor result and you have decided to release it anyway.

## Ownership

Reading is visible to organisation members who can see the definition. Running, cancelling and delivering are owner-only: visibility does not grant the ability to spend.