Launch a run

Launches a pipeline. A launch that needs approval is left awaiting approval, exactly as the Web UI would leave it; the person approves it in the web app, not through this call. The run is always launched inside an ecosystem, so X-Ecosystem-Id is required: without it the call is refused with status 400. Every run belongs to an ecosystem, for usage metering and for the runs list.

Last updated:

Launches a pipeline. A launch that needs approval is left awaiting approval, exactly as the Web UI would leave it; the person approves it in the web app, not through this call. The run is always launched inside an ecosystem, so X-Ecosystem-Id is required: without it the call is refused with status 400. Every run belongs to an ecosystem, for usage metering and for the runs list.

POST /api/v1/pipelines/{pipelineId}/runs

Authorization

Requires a signed-in person with this scope: runs:launch.

Parameters

NameInRequiredTypeDescription
X-Workspace-Idheaderyesstring (uuid)The workspace the call acts in. Take it from the workspace list.
X-Ecosystem-Idheaderyesstring (uuid)The ecosystem (within the workspace named by X-Workspace-Id) the call acts in. Must belong to that workspace; an ecosystem of another workspace, or one that does not exist, is refused with no further detail.
pipelineIdpathyesstring (uuid)The pipeline's id.

Request body

FieldTypeRequiredDescription
parameterValuesobjectnoPer action id, a map of parameter name to value (Script actions only).

Example request:

{
  "parameterValues": {}
}

Responses

201

The run has started.

FieldTypeRequiredDescription
executionIdstring (uuid)yes
pipelineIdstring (uuid)yes
statusstringyes
startedAtstring (date-time)yes
messagestringyes

Example response:

{
  "executionId": "6d4e5f60-7182-93a4-b5c6-d7e8f9a0b1c2",
  "pipelineId": "3a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
  "status": "PENDING",
  "startedAt": "2026-10-12T09:10:00Z",
  "message": "Run started."
}

202

The run is awaiting approval, so no run has started: executionId, pipelineId and startedAt are null, status is PENDING_APPROVAL, and message holds the id of the approval a person decides in the web app.

FieldTypeRequiredDescription
executionIdstring (uuid)yes
pipelineIdstring (uuid)yes
statusstringyes
startedAtstring (date-time)yes
messagestringyes

Example response:

{
  "executionId": null,
  "pipelineId": null,
  "status": "PENDING_APPROVAL",
  "startedAt": null,
  "message": "a1b2c3d4-e5f6-0718-293a-4b5c6d7e8f90"
}

400

Either pipelineId is not a valid id, or X-Ecosystem-Id is missing (ILLEGAL_ARGUMENT — see this operation's own description above).

FieldTypeRequiredDescription
messagestringyes
statusintegeryes
errorCodestringyes
timestampstring (date-time)no
pathstringno
detailsobjectno

404

There is no such pipeline.

FieldTypeRequiredDescription
messagestringyes
statusintegeryes
errorCodestringyes
timestampstring (date-time)no
pathstringno
detailsobjectno

409

Another run of this pipeline is already in progress.

FieldTypeRequiredDescription
errorCodeone of CONCURRENT_EXECUTIONyes
messagestringyes
blockingExecutionIdstringno
blockingExecutionStatusstringno