Sign in

v1

latestOpenAPI 3.1.02026-07-22136108233.0 KB
runs

Create Run

Create a new run.

The workflow must exist and belong to the authenticated organization. If machine_id is not provided, an available machine will be automatically selected. The run will be created with SCHEDULING status and a Temporal workflow will be started asynchronously.

post/v1/runs

Headers

Idempotency-Keystring
Example:550e8400-e29b-41d4-a716-446655440000

Unique key for idempotent requests. If provided, the server ensures the request is processed at most once. Retries with the same key return the original response. SDKs auto-generate this for write requests.

Request body

workflow_idstring uuid required
is_priorityboolean

Prioritize this run over non-priority runs when assigning an eligible machine. Does not preempt active runs or bypass session ordering.

main_promptstring nullable

Optional per-run prompt override. When provided, this run executes the supplied prompt text instead of the workflow's stored main_prompt.

main_agent_model_idstring uuid nullable

Optional per-run main agent ModelConfiguration.id override. Stored as run model_metadata.main_agent_model_id and used only for this run.

machine_idstring uuid nullable

Machine ID. If not provided, an available machine will be automatically selected.

pool_idsstring[] nullable

Pool IDs to filter available machines. Machine must belong to all of these pools (intersection). Ignored when machine_id is provided.

input_valuesobject nullable

Input values for workflow variables

sensitive_input_valuesobject nullable

Sensitive input values (supports nested objects). These are not stored and will be written to a secure vault and referenced by alias only. In workflow input_schema, sensitive root keys are validated under a '$' prefixed key (for example input key 'api_key' is '$api_key').

session_idstring uuid nullable

Join an existing session; overrides machine_id/pool_ids

start_sessionboolean nullable

Start a new session on the machine used by this run. Session ID will be this run's ID.

session_aliasstring nullable

Persist outputs under this alias for $ref in this session

release_session_afterboolean nullable

Release the session after this run completes successfully

Response

Successful Response

workflow_idstring uuid required
machine_idstring uuid nullable required
idstring uuid required
user_idstring uuid nullable
organization_idstring nullable
is_priorityboolean
status'scheduling' | 'running' | 'running_checks' | 'success' | 'cancelled' | 'task_failed' | 'error' required
errorstring[] nullable
output_dataobject nullable
input_attachment_idsstring[] nullable
output_attachment_idsstring[] nullable
run_message_historyobject[] nullable
input_valuesobject nullable
main_promptstring nullable

Per-run prompt override used for execution. Null means the run falls back to the workflow's current main_prompt.

pool_idsstring[] nullable
sensitive_input_aliasesobject nullable
usage_metadataobject nullable

Arbitrary usage/billing metadata captured during a run (schema is flexible)

session_idstring uuid nullable
session_aliasstring nullable
release_session_afterboolean nullable
created_atstring date-time required
started_atstring date-time nullable
ended_atstring date-time nullable