Skip to main content
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.
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.

​
Example: pinned prompt version

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'
  }
});

​
Example: always use latest workflow prompt

Omit main_prompt to keep the existing behavior: 
{
  "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: 
{
  "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: 
{
  "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.

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