---
title: "Queue a run of this suite"
method: POST
path: "/v1/agents/{agent_id}/simulation-suites/{suite_id}/runs"
---

# Queue a run of this suite

`POST /v1/agents/{agent_id}/simulation-suites/{suite_id}/runs`

## Request

- Base URL: `https://api.skysay.ai`
- URL: `https://api.skysay.ai/v1/agents/{agent_id}/simulation-suites/{suite_id}/runs`
- Auth: none declared

Returns 202 immediately with a durable queued run: request latency never depends on how long the suite takes to execute. The suite revision, its content hash and the compiled workflow snapshot are pinned at this moment, so an edit made while the run waits for a worker cannot change what it proves. idempotency_key is required and scoped to the organization -- replaying the same request returns the same run, and reusing one key for a different request is refused with 409. A run whose selected scenarios need a runner that is not deployed is refused with 422 unsupported_mode before anything is queued. Deterministic attempts make no model call and record a cost of zero; adaptive attempts are metered, and the run pins an upper-bound estimate, a model-call ceiling and the caller and evaluator identities before the first attempt starts. Nothing here is charged to a customer balance -- suite cost is reported by the simulation-suite ledger only.

## Path parameters

- `agent_id` string, required
- `suite_id` string, required

## Request body

- object
  - `idempotency_key` string, required
  - `pinned_source` 'draft' | 'published'
  - `scenario_ids` string[]: Run only these scenarios. Omit to run the whole suite.

## Response `202`

Durable queued run

## Other responses

- `400`: Missing idempotency_key or an unusable snapshot
- `404`: Suite not found, or Simulations Lab is not enabled
- `409`: The idempotency key was already used for a different request
- `422`: Typed refusal: unsupported_mode, no_scenarios, suite_archived, active_run_limit or organization_budget

---

[API](https://skmtc.dev/skysay/apis/skysay-api.md) · [All operations](https://skmtc.dev/skysay/apis/skysay-api/llms.txt) · [OpenAPI document](https://skmtc.dev/skysay/apis/skysay-api/revisions/148c7e111260?raw)