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

# Priority Runs

> Schedule urgent runs ahead of normal queued work without interrupting active runs or session order

Priority runs let you mark urgent automation work so Cyberdesk considers it before normal queued runs when a compatible machine becomes available.

Priority is a queue-selection preference, not preemption. It never interrupts a run that is already executing.

## How priority scheduling works

When Cyberdesk assigns queued runs to machines, it evaluates currently eligible priority runs before normal runs:

1. Priority runs with a specific machine requirement
2. Priority runs that can use any eligible machine
3. Normal runs with a specific machine requirement
4. Normal runs that can use any eligible machine

Within each group, runs retain their existing first-in, first-out order based on creation time.

<Info>
  Priority only changes the order of eligible queued work. Machine availability, pool membership, connection state, and other matching requirements still apply.
</Info>

## Sessions and chains keep their order

Priority does not let a later run skip an earlier run in the same session or chain. If step two is marked as priority while step one is still queued, step two remains blocked until step one is assigned and completed according to the normal session sequence.

For chain creation, one `is_priority` value applies to every step in the chain. The steps still execute in their declared order.

## Create a priority run

Set `is_priority` to `true` when creating a run. The field defaults to `false`.

<Tabs>
  <Tab title="Dashboard">
    In the new run dialog, select **Priority run**. The same checkbox is available for single runs, bulk runs, and chains.

    Priority runs are identified in the runs table and on the run detail page.
  </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",
        "is_priority": true
      }'
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const { data: run, error } = await client.runs.create({
      workflow_id: 'workflow-uuid',
      is_priority: true
    });
    ```
  </Tab>

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

    response = client.runs.create_sync(
        RunCreate(
            workflow_id="workflow-uuid",
            is_priority=True,
        )
    )
    ```
  </Tab>
</Tabs>

## Bulk runs and chains

Bulk creation applies the value to every run in the request:

```typescript theme={null}
await client.runs.bulkCreate({
  workflow_id: 'workflow-uuid',
  count: 25,
  is_priority: true
});
```

Chain creation applies the value to every step:

```typescript theme={null}
await client.runs.chain({
  is_priority: true,
  steps: [
    { workflow_id: 'workflow-step-one' },
    { workflow_id: 'workflow-step-two' }
  ]
});
```

## Retries

An in-place retry preserves the run's current priority by default. You can also promote or demote the run for its next scheduling attempt by including `is_priority` in the retry request.

```typescript theme={null}
await client.runs.retry('run-uuid', {
  is_priority: true
});
```

The dashboard preselects the run's current value in the retry dialog. Change **Priority run** before submitting to override it without creating a new run ID.

## Capacity planning

Priority runs are always considered before normal eligible runs. A sustained stream of priority work can therefore delay normal queued runs.

Use priority for work with a genuine scheduling need, such as time-sensitive customer operations, incident response, or deadline-bound processing. If most work is marked priority, the queue behaves much like a normal queue and regular runs may wait longer than expected.