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

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

## Schedule SDK

### `anyscale.schedule.apply`

Apply or update a schedule.

Returns the id of the schedule.

**Arguments**

-   **`config` ([ScheduleConfig](#scheduleconfig))**: The config options defining the schedule.

**Returns**: str

#### Examples

::::tabs

:::tab[Python]
```python
import anyscale
from anyscale.job.models import JobConfig
from anyscale.schedule.models import ScheduleConfig

anyscale.schedule.apply(
    ScheduleConfig(
        cron_expression="0 0 * * * *",
        job_config=JobConfig(
            name="my-job",
            entrypoint="python main.py",
            working_dir=".",
        )
    )
)
```
:::

::::

### `anyscale.schedule.set_state`

Set the state of a schedule.

Returns the id of the schedule.

**Arguments**

-   **`id` (str | None) = None**: The id of the schedule.
-   **`name` (str | None) = None**: The name of the schedule.
-   **`cloud` (str | None) = None**: The Anyscale Cloud to run this workload on. If not provided, the organization default will be used (or, if running in a workspace, the cloud of the workspace).
-   **`project` (str | None) = None**: Named project to use for the schedule. If not provided, the default project for the cloud will be used (or, if running in a workspace, the project of the workspace).
-   **`state` ([ScheduleState](#schedulestate))**: The state to set the schedule to.

**Returns**: str

#### Examples

::::tabs

:::tab[Python]
```python
import anyscale
from anyscale.schedule.models import ScheduleState

anyscale.schedule.set_state(
    id="my-schedule-id",
    state=ScheduleState.DISABLED,
)
```
:::

::::

### `anyscale.schedule.status`

Return the status of the schedule.

**Arguments**

-   **`id` (str | None) = None**: The id of the schedule.
-   **`name` (str | None) = None**: The name of the schedule.
-   **`cloud` (str | None) = None**: The Anyscale Cloud of the schedule. If not provided, the organization default will be used (or, if running in a workspace, the cloud of the workspace).
-   **`project` (str | None) = None**: Named project to use for the schedule. If not provided, the default project for the cloud will be used (or, if running in a workspace, the project of the workspace).

**Returns**: [ScheduleStatus](#schedulestatus)

#### Examples

::::tabs

:::tab[Python]
```python
import anyscale
anyscale.schedule.status(id="cronjob_yt389jvskwht9k2ygx7rj6iz62")
```
:::

::::

### `anyscale.schedule.trigger`

Trigger the execution of the schedule.

**Arguments**

-   **`id` (str | None) = None**: The id of the schedule.
-   **`name` (str | None) = None**: The name of the schedule.
-   **`cloud` (str | None) = None**: The Anyscale Cloud of the schedule. If not provided, the organization default will be used (or, if running in a workspace, the cloud of the workspace).
-   **`project` (str | None) = None**: Named project to use for the schedule. If not provided, the default project for the cloud will be used (or, if running in a workspace, the project of the workspace).

**Returns**: str

#### Examples

::::tabs

:::tab[Python]
```python
import anyscale
anyscale.schedule.trigger(id="cronjob_yt389jvskwht9k2ygx7rj6iz62")
```
:::

::::

### `anyscale.schedule.list`

List schedules with filtering and pagination.

Returns a ResultIterator that lazily fetches pages of schedules.

**Arguments**

-   **`name` (str | None) = None**: Filter by schedule name.
-   **`schedule_id` (str | None) = None**: Fetch a specific schedule by ID.
-   **`project` (str | None) = None**: Filter by project name.
-   **`cloud` (str | None) = None**: Filter by cloud name.
-   **`creator_id` (str | None) = None**: Filter by creator ID.
-   **`include_all_users` (bool) = False**: Include schedules from all users.
-   **`page_size` (int | None) = None**: Number of items per page.
-   **`max_items` (int | None) = None**: Maximum total items to return.
-   **`sort_field` (str | None) = None**: Field to sort by (NAME, ID, CREATED\_AT, NEXT\_TRIGGER\_AT).
-   **`sort_order` (str | None) = None**: Sort order (ASC or DESC).

**Returns**: ResultIterator\[[ScheduleStatus](#schedulestatus)\]

#### Examples

::::tabs

:::tab[Python]
```python
import anyscale
from anyscale.schedule.models import ScheduleStatus

# List all schedules
for schedule in anyscale.schedule.list(max_items=10):
    print(f"{schedule.name}: {schedule.state}")

# Filter by project
schedules = list(anyscale.schedule.list(project="my-project"))
```
:::

::::

### `anyscale.schedule.url`

Get the web UI URL for a schedule.

**Arguments**

-   **`id` (str | None) = None**: The schedule ID.
-   **`name` (str | None) = None**: The schedule name (requires cloud and project).
-   **`cloud` (str | None) = None**: Cloud name (required with name).
-   **`project` (str | None) = None**: Project name (required with name).

**Returns**: str

#### Examples

::::tabs

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

# Get URL by ID
url = anyscale.schedule.url(id="cronjob_xxx")
print(url)

# Get URL by name
url = anyscale.schedule.url(name="my-schedule", cloud="my-cloud", project="my-project")
print(url)
```
:::

::::

### `anyscale.schedule.delete`

Delete a schedule.

If the schedule is active, it will be automatically paused before deletion. The schedule must have no active triggered jobs. Returns the ID of the deleted schedule.

**Arguments**

-   **`id` (str | None) = None**: The schedule ID.
-   **`name` (str | None) = None**: The schedule name (requires cloud and project).
-   **`cloud` (str | None) = None**: Cloud name (required with name).
-   **`project` (str | None) = None**: Project name (required with name).

**Returns**: str

#### Examples

::::tabs

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

# Delete by ID
anyscale.schedule.delete(id="cronjob_xxx")

# Delete by name
anyscale.schedule.delete(name="my-schedule", cloud="my-cloud", project="my-project")
```
:::

::::

## Schedule models

### `ScheduleConfig`

Configuration options for a schedule.

#### Fields

-   **`job_config` (Dict | [JobConfig](/reference/sdk/job.md#jobconfig))**: Configuration of the job.
-   **`cron_expression` (str)**: A cron expression to define the frequency at which to run this cron job, for example '0 0 \* \* \*' is a cron expression that means 'run at midnight'. Visit crontab.guru to construct a precise cron\_expression.
-   **`timezone` (str)**: The timezone in which to interpret the cron\_expression. Default is Universal time (UTC). You can specify 'local' to use the local timezone

#### Python Methods

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

def options(self, **fields) -> ScheduleConfig
    """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
timezone: local
cron_expression: 0 0 * * * *
job_config:
    name: my-schedule-job
    entrypoint: python main.py
    max_retries: 5
```
:::

:::tab[Python]
```python
from anyscale.schedule.models import ScheduleConfig
from anyscale.job.models import JobConfig

config = ScheduleConfig(
    job_config=JobConfig(
        entrypoint="python main.py"
    ),
    timezone="local",
    cron_expression="0 0 * * *"
)
```
:::

::::

### `ScheduleState`

Current state of a schedule.

#### Values

-   **`ENABLED`**: The schedule is enabled. Jobs will be started according to this jobs cron expression.
-   **`DISABLED`**: The schedule is disabled. No jobs will be started until the schedule is reenabled.

### `ScheduleStatus`

Current status of a schedule.

#### Fields

-   **`config` ([ScheduleConfig](#scheduleconfig))**: Configuration of the schedule.
-   **`id` (str)**: Unique ID of the schedule (generated when the schedule is first submitted).
-   **`name` (str)**: Name of the schedule.
-   **`state` (str | [ScheduleState](#schedulestate))**: Current state of the schedule.

#### Python Methods

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

#### Examples

::::tabs

:::tab[Python]
```python
import anyscale
from anyscale.schedule.models import ScheduleStatus
status: ScheduleStatus = anyscale.schedule.status(name="my-schedule")
```
:::

:::tab[CLI]
```bash
$ anyscale schedule status -n my-schedule
id: cronjob_dfhqufws6s3issltpjgrdzcgyc
name: my-schedule
state: ENABLED
```
:::

::::

### `ScheduleSortField`

Fields available for sorting schedules.

#### Values

-   **`NAME`**: Sort by schedule name.
-   **`ID`**: Sort by schedule ID.
-   **`CREATED_AT`**: Sort by creation timestamp.
-   **`NEXT_TRIGGER_AT`**: Sort by next trigger timestamp.

---

Previous: [Resource quotas](/reference/sdk/resource-quotas.md) | Next: [Service account](/reference/sdk/service-account.md)