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

# Start a run

> Start a run for a live workspace, reserve the planned credits and begin asynchronous answer collection. Estimate the run first to review its cost.

Creates a run for a `LIVE` workspace and reserves the planned credit cost.
[Estimate the run](https://docs.qwairy.co/developers/endpoints/runs/estimate.md) first to inspect usable
targets and cost. Creating the run revalidates both.

Requires an active Business, Agency Business or Enterprise plan. Use an API token with write access enabled. See [Writing data](https://docs.qwairy.co/developers/writing-data.md) for
idempotency, conditional requests and error handling.

**Authorization** `string` *required*

Bearer token for your team.

**Idempotency-Key** `string` *required*

Unique key for this operation. Completed responses replay for 24 hours.

**brandId** `string` *required*

Workspace identifier. The workspace must belong to the token's team.

**promptIds** `string[]`

Up to 50 active prompt UUIDs. Omit to select all active prompts. If that would
exceed 50, explicitly select a smaller set.

**modelIds** `string[]`

Up to 20 Qwairy model codes. Omit or send `[]` to use the workspace's
selected monitoring models; prompts with their own models keep them. Premium
models need a plan that includes them, and stored premium selections your
plan no longer includes are skipped, as in the dashboard.

## Response

Returns `202 Accepted` with a `Location` header pointing to
[Get a run](https://docs.qwairy.co/developers/endpoints/runs/get.md), plus:

| Run field | Meaning |
| - | - |
| `runId` | The newly created run identifier |
| `promptCount`, `modelCount` | Usable target dimensions |
| `unsupportedModels` | Requested model codes excluded from the run |

Generation is asynchronous. The usable prompt/model combination is planned
atomically; insufficient balance or a concurrent target change rejects the request.

## Synthetic request and response

```bash theme={null}
curl -i -X POST "https://www.qwairy.co/api/v1/brands/$BRAND_ID/runs" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN" \
  -H "Idempotency-Key: weekly-run-2026-09-01" \
  -H "Content-Type: application/json" \
  -d '{}'
```

```json theme={null}
{
  "run":{
    "runId":"55555555-0000-4000-8000-000000000000",
    "promptCount":12,
    "modelCount":2,
    "unsupportedModels":[]
  }
}
```

## Follow progress

[Get a run](https://docs.qwairy.co/developers/endpoints/runs/get.md) returns planning details.
[List runs](https://docs.qwairy.co/developers/endpoints/runs/list.md) includes overall status, outcome
counts and progress. There are no public cancel, retry or refund endpoints.

## Errors

| Status | Code | Cause |
| - | - | - |
| 400 | `INVALID_REQUEST` | Invalid targets or more than 50 selected prompts |
| 403 | `INSUFFICIENT_PLAN` | A requested model is a premium model your plan does not include |
| 404 | `RESOURCE_NOT_FOUND` | Workspace or requested prompt is inaccessible |
| 409 | `CONFLICT` | Workspace is not live, there is no usable target, or a target changed during planning |
| 409 | `INSUFFICIENT_CREDITS` | The full run cannot be funded |
| 409 | `IDEMPOTENCY_CONFLICT` | The same key was used with a different request |

See [Error codes](https://docs.qwairy.co/developers/errors.md) for authentication, plan, idempotency
and server errors. On `429`, honor `Retry-After`; writes can return
`503 SERVICE_UNAVAILABLE` if the write limiter is unavailable.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.