---
title: "Create Run"
method: POST
path: "/v1/runs"
tags: ["runs"]
---

# Create Run

`POST /v1/runs`

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.

## Headers

- `Idempotency-Key` string

## Request body

- RunCreate — Schema for creating a run
  - `workflow_id` string, uuid, required
  - `is_priority` boolean — Prioritize this run over non-priority runs when assigning an eligible machine. Does not preempt active runs or bypass session ordering.
  - `main_prompt` string, 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_id` string, 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.
  - `model_metadata` WorkflowModelMetadata — JSONB-backed workflow model configuration metadata. Stored on the Workflow row as `model_metadata` to avoid adding many FK columns. All fields are optional; when missing/null, the system falls back to Cyberdesk defaults.
    - `main_agent_model_id` string, uuid, nullable — ModelConfiguration.id used for the main agent. Null → Cyberdesk default.
    - `cache_detection_model_id` string, uuid, nullable — ModelConfiguration.id used for cache detection. Null → Cyberdesk default.
    - `fallback_model_1_id` string, uuid, nullable — ModelConfiguration.id used as fallback 1 (global across agents).
    - `fallback_model_2_id` string, uuid, nullable — ModelConfiguration.id used as fallback 2 (global across agents).
  - `machine_id` string, uuid, nullable — Machine ID. If not provided, an available machine will be automatically selected.
  - `pool_ids` string[], nullable — Pool IDs to filter available machines. Machine must belong to all of these pools (intersection). Ignored when machine_id is provided.
  - `input_values` object, nullable — Input values for workflow variables
  - `file_inputs` FileInput[], nullable — Files to upload to the machine
    - `filename` string, required
    - `content` string, required — Base64 encoded file content
    - `target_path` string, nullable — Optional path on machine, defaults to ~/CyberdeskTransfers/
    - `cleanup_imports_after_run` boolean — Delete from machine after run completes
  - `sensitive_input_values` object, 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_id` string, uuid, nullable — Join an existing session; overrides machine_id/pool_ids
  - `start_session` boolean, nullable — Start a new session on the machine used by this run. Session ID will be this run's ID.
  - `session_alias` string, nullable — Persist outputs under this alias for $ref in this session
  - `release_session_after` boolean, nullable — Release the session after this run completes successfully

## Response `201`

Successful Response

- RunResponse — Run response schema
  - `workflow_id` string, uuid, required
  - `machine_id` string, uuid, nullable, required
  - `id` string, uuid, required
  - `user_id` string, uuid, nullable
  - `organization_id` string, nullable
  - `is_priority` boolean
  - `status` 'scheduling' | 'running' | 'running_checks' | 'success' | 'cancelled' | 'task_failed' | 'error', required
  - `error` string[], nullable
  - `output_data` object, nullable
  - `input_attachment_ids` string[], nullable
  - `output_attachment_ids` string[], nullable
  - `run_message_history` object[], nullable
  - `input_values` object, nullable
  - `main_prompt` string, nullable — Per-run prompt override used for execution. Null means the run falls back to the workflow's current main_prompt.
  - `model_metadata` WorkflowModelMetadata — JSONB-backed workflow model configuration metadata. Stored on the Workflow row as `model_metadata` to avoid adding many FK columns. All fields are optional; when missing/null, the system falls back to Cyberdesk defaults.
    - `main_agent_model_id` string, uuid, nullable — ModelConfiguration.id used for the main agent. Null → Cyberdesk default.
    - `cache_detection_model_id` string, uuid, nullable — ModelConfiguration.id used for cache detection. Null → Cyberdesk default.
    - `fallback_model_1_id` string, uuid, nullable — ModelConfiguration.id used as fallback 1 (global across agents).
    - `fallback_model_2_id` string, uuid, nullable — ModelConfiguration.id used as fallback 2 (global across agents).
  - `pool_ids` string[], nullable
  - `sensitive_input_aliases` object, nullable
  - `usage_metadata` object, nullable — Arbitrary usage/billing metadata captured during a run (schema is flexible)
  - `post_run_checks` RunPostRunCheckSnapshot[], nullable — Version-tolerant snapshot/results for the run's post-run checks.
    - `id` string, uuid, nullable
    - `post_run_check_id` string, uuid, nullable
    - `snapshot_version` integer, nullable
    - `name` string, nullable
    - `description` string, nullable
    - `type` 'run_attachment_exists' | 'run_attachment_image_check' | 'output_data_passes_schema_validation' | 'output_data_agentic_check'
    - `order` integer, nullable
    - `file_target_mode` 'exact' | 'regex' | 'loop_items'
    - `file_names` string[], nullable
    - `file_name_regex` string, nullable
    - `expected_match_count` integer, nullable
    - `expected_match_count_ref` string, nullable
    - `loop_input` string, nullable
    - `loop_item_filename_template` string, nullable
    - `allow_missing_attachments` boolean
    - `check_prompt` string, nullable
    - `model` string, uuid, nullable
    - `status` 'pending' | 'running' | 'success' | 'failed' | 'infra_error' | 'cancelled', required
    - `started_at` string, date-time, nullable
    - `ended_at` string, date-time, nullable
    - `error_message` string, nullable
    - `messages` string[], nullable
    - `matched_filenames` string[], nullable
  - `session_id` string, uuid, nullable
  - `session_alias` string, nullable
  - `release_session_after` boolean, nullable
  - `created_at` string, date-time, required
  - `started_at` string, date-time, nullable
  - `ended_at` string, date-time, nullable

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/cyberdesk-hq/apis/cyberdesk-cloud.md) · [All operations](https://skmtc.net/cyberdesk-hq/apis/cyberdesk-cloud/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/cyberdesk-hq/cyberdesk-cloud/revisions/830d2f48963d/schema)