> ## 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 Model Overrides

> Choose the main agent model for a single run without mutating the workflow

Per-run model overrides let you choose the main agent, or computer-use, model when you create a run.

Use this when your application decides which model to use at trigger time. For example, your runner UI might route simple jobs to one model and harder jobs to another, while still using one shared Cyberdesk workflow.

## Why this exists

Normally, a run uses the workflow's saved `model_metadata`. That is the right default when the workflow owns model selection.

If your system launches many concurrent runs from one workflow, patching the workflow's `model_metadata` before each run can race:

* run A should use model A
* run B should use model B
* both runs use the same workflow
* patching the workflow would mutate shared state

With a per-run model override, each run carries its own model selection. The workflow's saved model configuration stays unchanged.

## 1. List Available Models

First, fetch the model configurations available to your organization:

<Tabs>
  <Tab title="HTTP">
    ```bash theme={null}
    curl "https://api.cyberdesk.io/v1/model-configurations" \
      -H "Authorization: Bearer $CYBERDESK_API_KEY"
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const { data: modelConfigurations } = await client.model_configurations.list();
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    response = client.model_configurations.list_sync()
    model_configurations = response.data
    ```
  </Tab>
</Tabs>

Each model configuration includes an `id`, `name`, provider details, and flags such as `is_computer_use_model` and `is_archived`.

For the main agent, choose a model where:

* `is_computer_use_model` is `true`
* `is_archived` is `false`
* the model matches your cost, latency, and reliability needs

<Tip>
  Show users the model `name` in your UI, but store and send the model configuration `id` when creating a run.
</Tip>

## 2. Create a Run With a Model Override

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

<Tabs>
  <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_agent_model_id": "model-configuration-uuid",
        "input_values": {
          "account_id": "acct_123"
        }
      }'
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const { data: run } = await client.runs.create({
      workflow_id: "workflow-uuid",
      main_agent_model_id: "model-configuration-uuid",
      input_values: {
        account_id: "acct_123",
      },
    });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    from cyberdesk import RunCreate

    run = client.runs.create_sync(
        RunCreate(
            workflow_id=workflow_id,
            main_agent_model_id=model_configuration_id,
            input_values={"account_id": "acct_123"},
        )
    )
    ```
  </Tab>
</Tabs>

This applies only to the run you create. The workflow's saved `model_metadata` is not changed.

## Full Metadata Shape

You can also send `model_metadata` directly. This is useful if you want to override more model roles later while keeping the same payload shape as workflow-level model metadata:

```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.

## Fallback Behavior

Per-run model metadata is merged on top of the workflow's model metadata:

* provided run-level fields win
* omitted run-level fields fall back to the workflow
* if no run-level model override is provided, behavior is unchanged

For example, if the workflow has cache detection and fallback models configured, and the run only provides `main_agent_model_id`, the run uses:

* run-level `main_agent_model_id`
* workflow-level cache detection model
* workflow-level fallback models

## Validation

Cyberdesk validates model override IDs when the run is created.

The request fails with `400` if the model configuration:

* does not exist
* is not accessible to your organization
* conflicts between `main_agent_model_id` and `model_metadata.main_agent_model_id`

## When to Use This

Use per-run model overrides when:

* your runner UI lets users pick a model at trigger time
* different workflow steps or jobs should use different main agent models
* you batch many concurrent runs of one workflow
* the workflow should remain a stable template instead of mutable runtime state

Do not use this when the workflow itself should remain the single source of truth for model selection. In that case, update the workflow's model configuration and create runs without `main_agent_model_id`.

## Related

* [Model Configuration](/concepts/model-configuration)
* [Per-run Prompt Overrides](/concepts/per-run-prompt-overrides)