---
title: "Start a run"
method: POST
path: "/runs/{workflow_id}"
tags: ["runs"]
---

# Start a run

`POST /runs/{workflow_id}`

Creates one or more runs against the given workflow and queues them for execution. Pre-flight checks: balance sufficient, concurrency limit, workflow exists. Runs that fail to queue are marked FAILED immediately so they stop counting toward the concurrency limit.

## Path parameters

- `workflow_id` string, uuid, required — workflow to create runs for

## Request body

- RunCreateRequest — Request body for creating one or more runs.
  - `$schema` string, uri — A URL to the JSON Schema for this object.
  - `runs` RunConfig[], nullable, required — Per-run variable configurations. One run is created per entry.
    - `phone_id` string — PhoneID pins this run to a specific phone (for dedicated phones).
    - `variables` object[], nullable, required — Array of variable maps keyed by node ID.
  - `start_timeout_seconds` integer — How long a queued run may wait for a phone before it is auto-cancelled.

## Response `201`

Created

- RunCreateResponse — Returned after successfully creating one or more runs.
  - `$schema` string, uri — A URL to the JSON Schema for this object.
  - `run_ids` string[], nullable, required — List of created run identifiers.

## Other responses

- `default` — Error

## Changes

- **2026-07-23** `5a989777701c` — 1 breaking
  - for the `path` request parameter `workflow_id`, the format changed from no format to `uuid`
- **2026-07-18** `80c0e071bf67` — 1 warning
  - removed the request property `count`

[Change history](https://skmtc.dev/axilioai/apis/axilio-api/changes/runs/:workflow_id/post.md)

---

[API](https://skmtc.dev/axilioai/apis/axilio-api.md) · [All operations](https://skmtc.dev/axilioai/apis/axilio-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/axilioai/axilio-api/revisions/a0204e0956bc/schema)