> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cyberdesk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Per-run Prompt and Model Overrides

> Pin a run to a specific prompt or main agent model without mutating the workflow

Per-run overrides let you pass `main_prompt` or a main agent model override directly when creating a run.

Use this when your system owns prompt or model selection and wants a run to execute a specific version without updating the workflow's stored defaults.

## Why this exists

Normally, a run executes the workflow's current `main_prompt` and `model_metadata`.

That works well when the workflow itself is the source of truth, but it can create races if an external workflow builder stores prompt versions separately:

* run A should execute prompt v3 or model A
* run B should execute prompt v4 or model B
* both runs use the same workflow
* patching the workflow before each run would mutate shared state

With per-run overrides, each run carries its own prompt text or model metadata. Concurrent runs can use different prompt or model versions without racing on the workflow record.

## How it works

`POST /v1/runs` accepts optional `main_prompt`, `main_agent_model_id`, and `model_metadata` fields:

* If `main_prompt` is provided, that run executes the supplied prompt text.
* If `main_prompt` is omitted or `null`, the run falls back to the workflow's stored `main_prompt`.
* If `main_agent_model_id` is provided, that run uses the supplied main agent `ModelConfiguration.id`.
* If `model_metadata` is provided, its non-null fields override the workflow's `model_metadata` for that run.
* The workflow's stored prompt and model metadata are not changed.
* The run response includes `main_prompt` and `model_metadata`; `null` means the run uses workflow-level fallback.

<Info>
  Cyberdesk does not store prompt version history for you. Store version history and "latest vs pinned" logic in your system, then send the resolved prompt text when creating a run.
</Info>

## Example: pinned prompt version

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    const { data: run } = await client.runs.create({
      workflow_id: 'workflow-uuid',
      main_prompt: 'Prompt v3: open the CRM, find the account, and update the renewal date.',
      input_values: {
        account_id: 'acct_123',
        renewal_date: '2026-07-01'
      }
    });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    run = client.runs.create_sync(
        RunCreate(
            workflow_id=workflow_id,
            main_prompt="Prompt v3: open the CRM, find the account, and update the renewal date.",
            input_values={
                "account_id": "acct_123",
                "renewal_date": "2026-07-01",
            },
        )
    )
    ```
  </Tab>

  <Tab title="HTTP">
    ```bash theme={null}
    curl -X POST "https://api.cyberdesk.io/v1/runs" \
      -H "Authorization: Bearer $CYBERDESK_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "workflow_id": "workflow-uuid",
        "main_prompt": "Prompt v3: open the CRM, find the account, and update the renewal date.",
        "input_values": {
          "account_id": "acct_123",
          "renewal_date": "2026-07-01"
        }
      }'
    ```
  </Tab>
</Tabs>

## Example: always use latest workflow prompt

Omit `main_prompt` to keep the existing behavior:

```json theme={null}
{
  "workflow_id": "workflow-uuid",
  "input_values": {
    "account_id": "acct_123"
  }
}
```

This run uses whatever `main_prompt` is currently stored on the workflow when the run executes.

## Example: per-run main agent model

Use `main_agent_model_id` when you only need to override the CUA/main agent model:

```json theme={null}
{
  "workflow_id": "workflow-uuid",
  "main_agent_model_id": "model-configuration-uuid",
  "input_values": {
    "account_id": "acct_123"
  }
}
```

You can also provide the full `model_metadata` shape when you need to override more than the main agent model:

```json theme={null}
{
  "workflow_id": "workflow-uuid",
  "model_metadata": {
    "main_agent_model_id": "model-configuration-uuid"
  }
}
```

If both `main_agent_model_id` and `model_metadata.main_agent_model_id` are present, they must match.

For a full walkthrough of finding available model configuration IDs and choosing computer-use models, see [Per-run Model Overrides](/concepts/per-run-model-overrides).

## Input variables and validation

When `main_prompt` is provided on the run, Cyberdesk uses that prompt for prompt-variable handling on that run.

For example, if the override references `{account_id}`, that variable is treated as part of the run's prompt even if the workflow's stored prompt does not currently reference it.

If the workflow has an `input_schema`, the run's inputs are still validated against the workflow schema. Overrides only change runtime prompt/model selection for that run; they do not create or change the workflow schema.

## Interaction with Post-run Checks

Per-run prompt and model overrides do not change the workflow-level Post-run Check configuration.

One important guard stays tied to the stored workflow prompt: a run can only skip Post-run Checks through `declare_task_succeeded` with `skip_post_run_checks=True` when the workflow's stored prompt explicitly authorizes that behavior. Adding those words only in a per-run override does not authorize skipping checks.

## When to use this

Use per-run overrides when:

* you keep prompt versions in your own workflow builder
* you want a run pinned to a specific prompt version
* you choose the main agent model at trigger time
* you batch concurrent runs of the same workflow with different prompt or model versions
* you want the workflow's stored prompt to remain a mirror or default, not the runtime source of truth for every run

Do not use this when the workflow itself should remain the only editable source of prompt and model truth. In that case, update the workflow and create runs without per-run overrides.