---
title: "Update Run"
method: PATCH
path: "/v1/runs/{run_id}"
tags: ["runs"]
---

# Update Run

`PATCH /v1/runs/{run_id}`

Update a run's data.

Only the fields provided in the request body will be updated.
The run must belong to the authenticated organization.

## Path parameters

- `run_id` string, uuid, required

## Headers

- `Idempotency-Key` string

## Request body

- RunUpdate — Schema for updating a run
  - `status` 'scheduling' | 'running' | 'running_checks' | 'success' | 'cancelled' | 'task_failed' | 'error'
  - `error` string[], nullable
  - `output_data` object, nullable
  - `output_attachment_ids` string[], nullable
  - `run_message_history` object[], nullable
  - `input_values` object, nullable
  - `usage_metadata` object, nullable
  - `post_run_checks` RunPostRunCheckSnapshot[], nullable
    - `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
  - `started_at` string, date-time, nullable
  - `ended_at` string, date-time, nullable
  - `release_session_after` boolean, nullable

## Response `200`

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