> ## 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 to define a scheduled job.

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

```sh theme={null}
=> Deployed 🎉
=> Schedule details
Schedule: @hourly
Upcoming:
  1. 2024-08-30 18:00:00 UTC (2024-08-30 14:00:00 EDT)
  2. 2024-08-30 19:00:00 UTC (2024-08-30 15:00:00 EDT)
  3. 2024-08-30 20:00:00 UTC (2024-08-30 16:00:00 EDT)
```

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

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>