OpenAPI 3.1.0raw.githubusercontent.com2026-08-21161224637.5 KB

8978a4e735fa

Swarm runs

Launch a journey

Answers 202: the run row exists and its fan-out has started. It is not finished — poll GET /projects/{projectId}/journey-runs/{runId} until status leaves running.

SPENDS. A launch fans out into targets × sessionsPerTarget chat sessions, every one of which runs a model on your organization's account.

Two different 429s can come back and they mean different waits: the per-minute burst brake (retry in seconds) and your plan's daily launch cap (resets at UTC midnight). Both normally carry Retry-After — honor it when it is there, and back off on your own when it is not, rather than blocking on a header that may not come. A retried Idempotency-Key consumes NO quota.

post/projects/{projectId}/journeys/{journeyId}/runs

Headers

Idempotency-Keystring

Send one. A launch spends model credits, so a retry of a dropped response must not run the journey twice. Replaying a key returns the ORIGINAL run with deduped: true and starts no second runner.

Omitting the header is read as a request that declined to identify itself, and gets a FRESH run every time.

Request body

waveIdstring

Opaque id linking the sibling runs of one co-launched batch. Mint it yourself and reuse it across the launches you want grouped.

environmentIdsstring[]

Fan out across THESE environments instead of the journey's authored targets. NON-EMPTY when present: [] is a caller saying "across these" while naming none, and would have silently launched the authored targets instead. Silently running something other than what was asked for is bad anywhere; on an operation that spends it is worse. Omit the field to mean "as authored".

Response

The run was accepted and started.

idstring required

The run id. Poll it, or stop it with cancel.

journeyIdstring required

projectIdstring required

status'running' required

Always running — the run row exists and its fan-out has started. This is a 202: nothing here says the journey has finished, only that it is under way.

dedupedboolean required

True when an Idempotency-Key replayed onto a run that ALREADY existed, so nothing new was started. The response is otherwise identical, which is how a retry of a dropped request tells "I launched it" from "it was already going" without a second read.