Run a pipeline
/api/v1/pipelines/{pipeline_id}/runStart a run of this pipeline.
The run is admitted synchronously and then sequenced step by step: the response carries the pending run, and progress and outcome are polled from GET /pipelines/runs/{run_id}. Capacity and budget rejections surface here as 429.
An optional Idempotency-Key header makes the start retry-safe, scoped to the caller and this pipeline. A replay must carry the original payload; reusing a key with different input is rejected with 409.
Required access
Credentials: service principal, delegated token, user session
Scope: pipelines:invoke
Every step is authorized before the run is admitted, so a pipeline that references an agent the caller cannot invoke fails up front rather than part-way through. Runs started with a service-principal key have no acting user and are attributed to the key; steps fall back to the step agent's owner for anything user-scoped.
An organization-owned automation key, prefixed gsmc_sk_. Already bound to one organization, so it needs no X-Org-Id header. It carries no user identity: it never reaches a private resource however it is scoped, and a run it starts has no user for an interactive tool to reach.
In: header
Path Parameters
uuidHeader Parameters
Makes this start retry-safe. Generate one stable value per intended execution and reuse it only when retrying that same execution: the key is scoped to the caller and the target resource, and re-presenting it returns the run already admitted instead of starting a second one. A replay must carry the original payload — the same key with different input answers 409.
Selects the active organization for a credential that belongs to more than one. Service-principal keys are bound to a single organization and ignore it.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Request body for executing a pipeline.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/api/v1/pipelines/497f6eca-6276-4993-bfeb-53cbbbba6f08/run" \ -H "Authorization: Bearer $GUEST_MACHINES_API_KEY" \ -H "Idempotency-Key: 9f8c2b7a-1d3e-4f5a-8b6c-2e1d0a9f8c7b" \ -H "Content-Type: application/json" \ -d '{ "input_data": { "repository": "acme/checkout", "since": "2026-07-01" }, "project_tag": "checkout-rewrite" }'{ "run": { "id": 1, "pipeline_id": "ec036e81-7903-4e4d-bbfa-ac8516341cf0", "actor_principal_type": "agent", "service_principal_id": "0d57b427-9ed2-4a5e-b0bd-32c8ce299b8e", "oauth_client_id": "727760ca-b97d-449c-90e5-7773c8142d5d", "status": "cancelled", "current_step": 0, "current_iteration": 1, "input_data": {}, "output_data": {}, "error": "string", "limit_detail": { "error": "limit_exceeded", "limit_type": "concurrency.global", "scope": "global", "message": "string", "scope_id": "string", "limit": 0, "actual": 0, "retry_after_seconds": 0 }, "failed_step": 0, "started_at": "2019-08-24T14:15:22Z", "completed_at": "2019-08-24T14:15:22Z", "duration_seconds": 0, "total_tokens": 0, "total_cost_usd": 0, "total_retries": 0, "total_tool_calls": 0, "total_tool_attempts": 0, "whole_step_replay_safe": true, "created_at": "2019-08-24T14:15:22Z" }}{ "detail": "string", "error_code": "string", "request_id": "string"}{ "detail": "string", "error_code": "string", "request_id": "string"}{ "detail": "string", "error_code": "string", "request_id": "string"}{ "detail": "string", "error_code": "string", "request_id": "string"}{ "detail": "string", "error_code": "string", "request_id": "string"}{ "detail": "string", "error_code": "string", "request_id": "string"}{ "detail": "string", "error_code": "string", "request_id": "string"}{ "detail": "string", "error_code": "string", "request_id": "string"}