---
title: "Scheduler SDK reference"
description: "Customer-hosted cloud features"
---

# Scheduler SDK reference

#### Customer-hosted cloud features

:::note
Some features are only available on customer-hosted clouds. Reach out to [support@anyscale.com](mailto:support@anyscale.com) for info.
:::

## Scheduler SDK

### `anyscale.scheduler.apply_config`

Apply a scheduler config (creates a new active version). Returns the new version number.

The previous active version becomes inactive but remains queryable via list\_config\_versions and get\_config(version=N). Schema is validated locally before the API call; cross-reference checks (queue refs, flavor refs) happen on the server.

**Arguments**

-   **`config` ([SchedulerConfig](#schedulerconfig) | Dict\[str, Any\])**: Scheduler config to apply. Either a SchedulerConfig dataclass or a dict matching the API schema.

**Returns**: int

#### Examples

::::tabs

:::tab[Python]
```python
import anyscale
from anyscale.scheduler.models import SchedulerConfig

# Load from a YAML file (recommended).
config = SchedulerConfig.from_yaml("scheduler-config.yaml")
version = anyscale.scheduler.apply_config(config)
print(f"Applied scheduler config version {version}")

# Or pass a dict directly.
anyscale.scheduler.apply_config({
    "resource_flavors": [...],
    "resource_queues": [...],
    "scheduling_rules": [...],
})
```
:::

::::

### `anyscale.scheduler.get_config`

Get the active scheduler config (or a specific version).

Returns the version number, active flag, creator, created\_at, and the full SchedulerConfig.

**Arguments**

-   **`version` (int | None) = None**: Specific version to fetch. Omit to fetch the active config.

**Returns**: [SchedulerConfigVersion](#schedulerconfigversion)

#### Examples

::::tabs

:::tab[Python]
```python
import anyscale

# Active config (default).
active = anyscale.scheduler.get_config()
print(active.version, active.config)

# A specific historical version.
v3 = anyscale.scheduler.get_config(version=3)
```
:::

::::

### `anyscale.scheduler.list_config_versions`

List scheduler config version history (newest first).

Returns metadata (version, created\_at, creator\_id) without the config blob. Use get\_config(version=N) to fetch the full config for a specific version.

**Arguments**

-   **`max_items` (int) = 10**: Maximum number of versions to return. Defaults to 10.

**Returns**: List\[[SchedulerConfigVersionSummary](#schedulerconfigversionsummary)\]

#### Examples

::::tabs

:::tab[Python]
```python
import anyscale

# Default: 10 most recent versions.
for summary in anyscale.scheduler.list_config_versions():
    print(summary.version, summary.created_at, summary.creator_id)

# Fetch any number; the SDK paginates internally.
recent = anyscale.scheduler.list_config_versions(max_items=200)
```
:::

::::

## Scheduler models

### `SchedulerConfig`

Top-level Global Resource Scheduler config.

A scheduler config is org-scoped. Apply to create a new active version; previous versions remain queryable.

#### Fields

-   **`resource_flavors` (List\[[ResourceFlavor](#resourceflavor)\] | None)**: Named flavors describing which instances satisfy each flavor (via match expressions) plus optional advanced launch overrides.
-   **`resource_queues` (List\[[ResourceQueue](#resourcequeue)\] | None)**: Queues requests land in. Each carries optional preemption and per-flavor quotas.
-   **`scheduling_rules` (List\[[SchedulingRule](#schedulingrule)\] | None)**: Rules routing incoming requests to a queue based on a structured label selector.

#### Python Methods

```python
def __init__(self, **fields) -> SchedulerConfig
    """Construct a model with the provided field values set."""

def options(self, **fields) -> SchedulerConfig
    """Return a copy of the model with the provided field values overwritten."""

def to_dict(self) -> Dict[str, Any]
    """Return a dictionary representation of the model."""
```

#### Examples

::::tabs

:::tab[YAML]
```yaml
resource_flavors:
  - name: spot
    selector:
      - key: market
        operator: in
        values: [spot]
resource_queues:
  - name: research
    preemption:
      within_resource_queue: lower_priority
    resource_groups:
      - covered_resources: [gpu]
        flavors:
          - name: spot
            resources:
              - name: gpu
                nominal_quota: 64
scheduling_rules:
  - resource_queue: research
    selector:
      - key: team
        operator: in
        values: [research]
    priority_policy:
      default: 50
      min: 0
      max: 100
      on_violation: reject
```
:::

:::tab[Python]
```python
import anyscale
from anyscale.scheduler.models import SchedulerConfig

# Load from a YAML file
config = SchedulerConfig.from_yaml("scheduler-config.yaml")

# Or build programmatically
config = SchedulerConfig(
    resource_flavors=[...],
    resource_queues=[...],
    scheduling_rules=[...],
)

anyscale.scheduler.apply_config(config)
```
:::

::::

### `ResourceFlavor`

A named flavor with an optional match-expression selector and advanced launch overrides.

#### Fields

-   **`name` (str)**: Unique name for this resource flavor.
-   **`selector` (List\[[MatchExpression](#matchexpression)\] | None)**: Match expressions describing which instances satisfy this flavor.
-   **`advanced_instance_config` (Dict\[str, Any\] | None)**: Cloud-provider-specific advanced launch overrides for instances of this flavor.

#### Python Methods

```python
def to_dict(self) -> Dict[str, Any]
    """Return a dictionary representation of the model."""
```

#### Examples

::::tabs

:::tab[Python]
```python
from anyscale.scheduler.models import ResourceFlavor, MatchExpression, Operator

flavor = ResourceFlavor(
    name="spot",
    selector=[
        MatchExpression(key="market", operator=Operator.IN, values=["spot"]),
    ],
)
```
:::

::::

### `MatchExpression`

A structured label-match used in scheduling-rule and flavor selectors.

#### Fields

-   **`key` (str)**: Label key to match against.
-   **`operator` ([Operator](#operator))**: Match operator: 'in', 'not\_in', 'exists', or 'does\_not\_exist'.
-   **`values` (List\[str\] | None)**: Values for 'in'/'not\_in' (must be non-empty). Must be empty or omitted for 'exists'/'does\_not\_exist'.

#### Python Methods

```python
def to_dict(self) -> Dict[str, Any]
    """Return a dictionary representation of the model."""
```

#### Examples

::::tabs

:::tab[Python]
```python
from anyscale.scheduler.models import MatchExpression, Operator

expr = MatchExpression(key="team", operator=Operator.IN, values=["research", "ml"])
```
:::

::::

### `Operator`

Operator used in a match expression.

#### Values

-   **`IN`**: Key's value is in the supplied values list.
-   **`NOT_IN`**: Key's value is not in the supplied values list.
-   **`EXISTS`**: Key is present on the request (values must be empty).
-   **`DOES_NOT_EXIST`**: Key is absent from the request (values must be empty).

### `ResourceQueue`

A queue requests are routed to. Carries optional preemption and per-flavor quotas.

#### Fields

-   **`name` (str)**: Unique name for this resource queue.
-   **`preemption` ([PreemptionPolicy](#preemptionpolicy) | None)**: Preemption settings for this queue.
-   **`resource_groups` (List\[[ResourceGroup](#resourcegroup)\] | None)**: Quota groups, one per set of covered resources, with per-flavor capacity.

#### Python Methods

```python
def to_dict(self) -> Dict[str, Any]
    """Return a dictionary representation of the model."""
```

#### Examples

::::tabs

:::tab[Python]
```python
from anyscale.scheduler.models import ResourceQueue

queue = ResourceQueue(name="research")
```
:::

::::

### `ResourceGroup`

A group of flavors that share the same set of covered resources.

#### Fields

-   **`covered_resources` (List\[str\])**: Resources covered by this group (e.g. \['gpu'\] or \['cpu', 'memory\_gb'\]).
-   **`flavors` (List\[[FlavorQuota](#flavorquota)\])**: Flavor-level quotas for the resources in covered\_resources.

#### Python Methods

```python
def to_dict(self) -> Dict[str, Any]
    """Return a dictionary representation of the model."""
```

#### Examples

::::tabs

:::tab[Python]
```python
from anyscale.scheduler.models import ResourceGroup, FlavorQuota, ResourceQuotaSpec

group = ResourceGroup(
    covered_resources=["gpu"],
    flavors=[
        FlavorQuota(
            name="spot",
            resources=[ResourceQuotaSpec(name="gpu", nominal_quota=64)],
        ),
    ],
)
```
:::

::::

### `FlavorQuota`

Per-flavor quota specs within a resource group.

#### Fields

-   **`name` (str)**: Name of the resource flavor this quota applies to.
-   **`resources` (List\[[ResourceQuotaSpec](#resourcequotaspec)\] | None)**: Per-resource quotas (e.g. one entry per covered resource). A covered resource omitted here (or an empty list) gets unlimited quota.

#### Python Methods

```python
def to_dict(self) -> Dict[str, Any]
    """Return a dictionary representation of the model."""
```

#### Examples

::::tabs

:::tab[Python]
```python
from anyscale.scheduler.models import FlavorQuota, ResourceQuotaSpec

flavor_quota = FlavorQuota(
    name="spot",
    resources=[ResourceQuotaSpec(name="gpu", nominal_quota=64)],
)
```
:::

::::

### `ResourceQuotaSpec`

Quota for a single resource (e.g. gpu, cpu) within a flavor.

#### Fields

-   **`name` (str)**: Resource name (e.g. 'gpu', 'cpu').
-   **`nominal_quota` (float | None)**: Guaranteed capacity for this queue+flavor+resource (up to 3 decimal places). Omit for unlimited quota; an explicit 0 blocks it.

#### Python Methods

```python
def to_dict(self) -> Dict[str, Any]
    """Return a dictionary representation of the model."""
```

#### Examples

::::tabs

:::tab[Python]
```python
from anyscale.scheduler.models import ResourceQuotaSpec

quota = ResourceQuotaSpec(name="gpu", nominal_quota=64)
```
:::

::::

### `PreemptionPolicy`

Preemption settings for a resource queue.

#### Fields

-   **`within_resource_queue` ([PreemptionPolicyWithinResourceQueue](#preemptionpolicywithinresourcequeue) | None)**: Whether to preempt strictly lower-priority requests within this queue.

#### Python Methods

```python
def to_dict(self) -> Dict[str, Any]
    """Return a dictionary representation of the model."""
```

#### Examples

::::tabs

:::tab[Python]
```python
from anyscale.scheduler.models import (
    PreemptionPolicy,
    PreemptionPolicyWithinResourceQueue,
)

policy = PreemptionPolicy(
    within_resource_queue=PreemptionPolicyWithinResourceQueue.LOWER_PRIORITY,
)
```
:::

::::

### `PreemptionPolicyWithinResourceQueue`

Preemption behavior for requests within the same resource queue.

#### Values

-   **`NEVER`**: Never preempt requests within the same queue.
-   **`LOWER_PRIORITY`**: Preempt strictly lower-priority requests in the same queue.

### `SchedulingRule`

Routes incoming requests to a queue based on a structured label selector.

#### Fields

-   **`resource_queue` (str)**: Name of the queue requests matching this rule are routed to.
-   **`selector` (List\[[MatchExpression](#matchexpression)\] | None)**: Match expressions evaluated against request labels. Omit to match all requests not matched by an earlier rule.
-   **`priority_policy` ([PriorityPolicy](#prioritypolicy) | None)**: Priority bounds applied to requests matched by this rule.

#### Python Methods

```python
def to_dict(self) -> Dict[str, Any]
    """Return a dictionary representation of the model."""
```

#### Examples

::::tabs

:::tab[Python]
```python
from anyscale.scheduler.models import SchedulingRule, MatchExpression, Operator

rule = SchedulingRule(
    resource_queue="research",
    selector=[MatchExpression(key="team", operator=Operator.IN, values=["research"])],
)
```
:::

::::

### `PriorityPolicy`

Priority bounds applied to requests matched by a scheduling rule.

#### Fields

-   **`default` (int | None)**: Default priority assigned to matching requests.
-   **`min` (int | None)**: Minimum allowed priority.
-   **`max` (int | None)**: Maximum allowed priority.
-   **`on_violation` ([OnViolationAction](#onviolationaction) | None)**: Action when a request's priority is outside \[min, max\]: 'reject' rejects, 'force\_update' clamps.

#### Python Methods

```python
def to_dict(self) -> Dict[str, Any]
    """Return a dictionary representation of the model."""
```

#### Examples

::::tabs

:::tab[Python]
```python
from anyscale.scheduler.models import PriorityPolicy, OnViolationAction

policy = PriorityPolicy(default=50, min=0, max=100, on_violation=OnViolationAction.REJECT)
```
:::

::::

### `OnViolationAction`

Action to take when a request priority is outside the policy's \[min, max\].

#### Values

-   **`REJECT`**: Reject the request when its priority is outside \[min, max\].
-   **`FORCE_UPDATE`**: Clamp the priority to the nearest in-range value and continue.

### `SchedulerConfigVersion`

A specific version of a scheduler config (active or historical).

#### Fields

-   **`version` (int)**: Monotonic version number for this config.
-   **`is_active` (bool)**: Whether this is the currently active config.
-   **`created_at` (datetime)**: Timestamp at which this version was applied.
-   **`creator_id` (str)**: User ID of the principal that applied this version.
-   **`config` ([SchedulerConfig](#schedulerconfig))**: The full scheduler config for this version.

#### Python Methods

```python
def to_dict(self) -> Dict[str, Any]
    """Return a dictionary representation of the model."""
```

#### Examples

::::tabs

:::tab[Python]
```python
import anyscale

version = anyscale.scheduler.get_config()
print(version.version, version.is_active, version.config)
```
:::

::::

### `SchedulerConfigVersionSummary`

Metadata-only summary of a scheduler config version (used by `list`).

#### Fields

-   **`version` (int)**: Monotonic version number.
-   **`created_at` (datetime)**: Timestamp at which this version was applied.
-   **`creator_id` (str)**: User ID of the principal that applied this version.

#### Python Methods

```python
def to_dict(self) -> Dict[str, Any]
    """Return a dictionary representation of the model."""
```

#### Examples

::::tabs

:::tab[Python]
```python
import anyscale

for v in anyscale.scheduler.list_config_versions():
    print(v.version, v.created_at, v.creator_id)
```
:::

::::

---

Previous: [Schedule](/reference/sdk/schedule.md) | Next: [Service account](/reference/sdk/service-account.md)