---
title: "Retry Run"
method: POST
path: "/v1/runs/{run_id}/retry"
tags: ["runs"]
---

# Retry Run

`POST /v1/runs/{run_id}/retry`

Retry an existing run in-place (same run_id).

- Rejects if run is active (scheduling or running).
- Always clears previous outputs/history/output attachments.
- Replaces input attachments if `file_inputs` are provided.
- Optionally overrides inputs, sensitive inputs, session/machine/pools.
- Triggers immediate assignment attempt unless the session is busy.

## Path parameters

- `run_id` string, uuid, required

## Headers

- `Idempotency-Key` string

## Request body

- RunRetry — Options for retrying an existing run in-place (same run_id). Notes: - If `file_inputs` are provided, existing input attachments are replaced. - Prior outputs, history, and output attachments are always cleared as part of retry. - Retry is only allowed for terminal runs (success, task_failed, error, or cancelled).
  - `input_values` object, nullable — Override input values for workflow variables
  - `sensitive_input_values` object, nullable — Provide new sensitive inputs (supports nested objects); stored in vault and mapped to aliases
  - `file_inputs` FileInput[], nullable — Provide new input files for this retry; replaces existing input attachments
    - `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
  - `machine_id` string, uuid, nullable — Override specific machine for this retry
  - `pool_ids` string[], nullable — Override pool filters if not using a specific machine
  - `reuse_session` boolean, nullable — Keep existing session_id. If false and no session_id provided, clears session fields
  - `session_id` string, uuid, nullable — Set/override session_id for this retry
  - `start_session` boolean, nullable — Start a fresh new session for this retry (creates new session_id)
  - `session_alias` string, nullable — Set/override session_alias for this retry (used with start_session or session_id)
  - `release_session_after` boolean, nullable — Override release_session_after behavior for this retry
  - `is_priority` boolean, nullable — Override priority for this retry. If omitted, the run keeps its existing priority.

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