---
title: "Bulk Create Runs"
method: POST
path: "/v1/runs/bulk"
tags: ["runs"]
---

# Bulk Create Runs

`POST /v1/runs/bulk`

Create multiple runs with the same configuration.

This endpoint creates multiple runs efficiently:
- All runs are created in a single database transaction
- Temporal workflows are started asynchronously
- Returns immediately with created run details

Maximum 1000 runs can be created in a single request.

## Headers

- `Idempotency-Key` string

## Request body

- RunBulkCreate — Schema for bulk creating runs
  - `workflow_id` string, uuid, required
  - `is_priority` boolean — Prioritize every created run over non-priority runs when assigning eligible machines.
  - `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
  - `count` integer, required — Number of runs to create (max 1000)
  - `sensitive_input_values` object, nullable — Sensitive input values (supports nested objects) to store in the secure vault per run. Not persisted in our database. In workflow input_schema, sensitive root keys are validated under a '$' prefixed key.
  - `session_id` string, uuid, nullable — Join an existing session; overrides machine_id/pool_ids for all runs
  - `start_session` boolean, nullable — Start a new session for these runs; a new UUID will be generated and set on all runs. The first run will attempt to reserve a machine.

## Response `201`

Successful Response

- RunBulkCreateResponse — Response for bulk run creation
  - `created_runs` RunResponse[], required
    - `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
  - `failed_count` integer
  - `errors` string[]

## 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/versions/830d2f48963d/schema)