> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beam.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Scheduled Jobs

> How to run workloads on a schedule.

## Run Scheduled Jobs

Use the `@schedule` decorator with a five-field cron expression or one of the predefined schedules below. Schedules use UTC. Calling `.remote()` executes one invocation; deploying enables the recurring schedule.

```python theme={null}
from beam import schedule


@schedule(when="@weekly", name="weekly-task")
def task():
    print("Hi, from your weekly scheduled task!")
```

To schedule it, run `beam deploy`:

```sh theme={null}
beam deploy app.py:task
```

You'll see the upcoming jobs listed in the console.

## Scheduling Options

The following predefined schedules can be used in the `when` parameter:

| **Predefined Schedule** | **Description** | **Cron Expression** |
| - | - | - |
| `@yearly` (or `@annually`) | Run once a year at midnight on January 1st | `0 0 1 1 *` |
| `@monthly` | Run once a month at midnight on the first day of the month | `0 0 1 * *` |
| `@weekly` | Run once a week at midnight on Sunday | `0 0 * * 0` |
| `@daily` (or `@midnight`) | Run once a day at midnight | `0 0 * * *` |
| `@hourly` | Run once an hour at the beginning of the hour | `0 * * * *` |

## Stopping Scheduled Jobs

You can stop a scheduled job from running by using the `beam deployment stop` CLI command.

First, list the upcoming jobs with `beam deployment list`:

```sh theme={null}
  ID                       Name                   Active   Version   Created At      Updated At      Stub Name                 Workspace Name
 ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  10c192b6-6489-42c9-a3…   schedule               Yes            2   9 minutes ago   9 minutes ago   schedule/deployment/ap…   f6fa28
```

Then reference the **Deployment ID** to stop a job:

```sh theme={null}
$ beam deployment stop 10c192b6-6489-42c9-a3bf-75c52ad1816b

Stopped 10c192b6-6489-42c9-a3bf-75c52ad1816b
```

## Gotchas

<Tip>
  If you deploy a new version of your scheduled job, the previous schedule will be disabled.
</Tip>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.