---
title: "Start a run"
method: POST
path: "/v1/suites/{suiteId}/runs"
tags: ["Runs"]
---

# Start a run

`POST /v1/suites/{suiteId}/runs`

## Request

- Base URL: `https://api.ironfang.com/rig`
- URL: `https://api.ironfang.com/rig/v1/suites/{suiteId}/runs`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Starts a run of the suite's current version and allocates every resource the definition declares: a fresh inbox address, callback URL, mock URL or route label each, unguessable and unique to this run. The run is active until it is finished, cancelled or its TTL passes, after which its resources stop accepting activity and its timeline is read-only. Send an Idempotency-Key to make a retry return the run it already started (200 rather than 201). An organisation may have at most 50 active runs at once (a run is active until it is finished, cancelled or its TTL passes); the next start is refused with 429 `active_run_limit` until one ends. The limit is capacity, the same on every account. Needs rig.run. Public effect: the allocated addresses and URLs are reachable from the Internet for the life of the run.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `external_id` string: Your own reference, such as a CI run id.
  - `reason` string
  - `ttl` string: Run lifetime as a duration ("30m", "2h"), 1m to 24h; defaults to the suite's defaults.run_ttl.

## Response `200`

The run this Idempotency-Key already started

- RunWithResources
  - `resources` Resource[], required
    - `config` object
    - `created_at` string, date-time, required
    - `email_address` string: For email resources - the inbox that receives for this run.
    - `expires_at` string, date-time, required
    - `id` string, uuid, required
    - `name` string, required
    - `organisation_id` string, uuid, required
    - `public_url` string, uri: For callback and mock resources - the unguessable URL to configure elsewhere.
    - `route_label` string: For connector routes, and callbacks forwarded through one.
    - `run_id` string, uuid, required
    - `scope` 'run', required
    - `type` 'email' | 'callback' | 'mock_http' | 'connector_route', required
  - `run` Run, required
    - `created_at` string, date-time, required
    - `created_by` string
    - `expires_at` string, date-time, required
    - `external_id` string
    - `finished_at` string, date-time
    - `id` string, uuid, required
    - `organisation_id` string, uuid, required
    - `outcome` 'pass' | 'fail' | 'none': Present once finished.
    - `project_id` string, uuid, required
    - `reason` string
    - `started_at` string, date-time, required
    - `status` 'active' | 'finished' | 'cancelled' | 'expired', required
    - `suite_id` string, uuid, required
    - `suite_version_id` string, uuid, required
    - `ttl_seconds` integer, required

## Other responses

- `201`: Run started and resources allocated
- `400`: The body is not one strict JSON value of the documented shape (`invalid_json`).
- `401`: No credential, an invalid one, or a delegated token where none is accepted (`unauthorized`, `invalid_api_key`, `delegated_not_allowed`).
- `403`: The credential lacks the permission or scope, or names another organisation (`forbidden`, `insufficient_scope`).
- `404`: No such object in this organisation (`not_found`).
- `409`: A name is already taken, or the target is archived (`conflict`, `archived`).
- `422`: A field is invalid; the message names it (`invalid_request`).
- `429`: The organisation already has its limit of 50 active runs (`active_run_limit`); finish or cancel one to start another

---

[API](https://skmtc.dev/ironfang/apis/ironfang-rig-api.md) · [All operations](https://skmtc.dev/ironfang/apis/ironfang-rig-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ironfang/apis/ironfang-rig-api/revisions/3e86a312dad1?raw)