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:
curl "https://api.cyberdesk.io/v1/model-configurations" \
-H "Authorization: Bearer $CYBERDESK_API_KEY"
const { data: modelConfigurations } = await client.model_configurations.list();
response = client.model_configurations.list_sync()
model_configurations = response.data
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 trueis_archived is false- the model matches your cost, latency, and reliability needs
Show users the model name in your UI, but store and send the model configuration id when creating a run.
2. Create a Run With a Model Override
Use main_agent_model_id when you only need to override the main agent model:
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"
}
}'
const { data: run } = await client.runs.create({
workflow_id: "workflow-uuid",
main_agent_model_id: "model-configuration-uuid",
input_values: {
account_id: "acct_123",
},
});
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"},
)
)
model_metadata is not changed.
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:
{
"workflow_id": "workflow-uuid",
"model_metadata": {
"main_agent_model_id": "model-configuration-uuid"
}
}
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.
