Cron Triggers

Background

Cron Triggers allow users to map a cron expression to a Worker using a scheduled() handler that enables Workers to be executed on a schedule.

Cron Triggers are ideal for running periodic jobs, such as for maintenance or calling third-party APIs to collect up-to-date data. Workers scheduled by Cron Triggers will run on underutilized machines to make the best use of Cloudflare's capacity and route traffic efficiently.

Note

Cron Triggers can also be combined with Workflows to trigger multi-step, long-running tasks. You can bind to a Workflow from directly from your Cron Trigger to execute a Workflow on a schedule.

Cron Triggers execute on UTC time.

Add a Cron Trigger

1. Define a scheduled event listener

To respond to a Cron Trigger, you must add a "scheduled" handler to your Worker.

JavaScript

export default {
  async scheduled(controller, env, ctx) {
    console.log("cron processed");
  },
};

TypeScript

interface Env {}
export default {
  async scheduled(
    controller: ScheduledController,
    env: Env,
    ctx: ExecutionContext,
  ) {
    console.log("cron processed");
  },
};

Python

from workers import handler

@handler
async def on_scheduled(controller, env, ctx):
  print("cron processed")

Refer to the following additional examples to write your code:

• Setting Cron Triggers
• Multiple Cron Triggers

2. Update configuration

After you have updated your Worker code to include a "scheduled" event, you must update your Worker project configuration.

Via the Wrangler configuration file

If a Worker is managed with Wrangler, Cron Triggers should be exclusively managed through the Wrangler configuration file.

Refer to the example below for a Cron Triggers configuration:

wrangler.jsonc

{
  "triggers": {
    "crons": [
      "*/3 * * * *",
      "0 15 1 * *",
      "59 23 LW * *"
    ]
  }
}

wrangler.toml

[triggers]
# Schedule cron triggers:
# - At every 3rd minute
# - At 15:00 (UTC) on first day of the month
# - At 23:59 (UTC) on the last weekday of the month
crons = [ "*/3 * * * *", "0 15 1 * *", "59 23 LW * *" ]

You also can set a different Cron Trigger for each environment in your Wrangler configuration file. You need to put the [triggers] table under your chosen environment. For example:

wrangler.jsonc

{
  "env": {
    "dev": {
      "triggers": {
        "crons": [
          "0 * * * *"
        ]
      }
    }
  }
}

wrangler.toml

[env.dev.triggers]
crons = ["0 * * * *"]

Via the dashboard

To add Cron Triggers in the Cloudflare dashboard:

1. Log in to the Cloudflare dashboard ↗ and select your account.
2. In Account Home, select Workers & Pages.
3. In Overview, select your Worker > Settings > Triggers > Cron Triggers.

Supported cron expressions

Cloudflare supports cron expressions with five fields, along with most Quartz scheduler ↗-like cron syntax extensions:

Field	Values	Characters
Minute	0-59	* , - /
Hours	0-23	* , - /
Days of Month	1-31	* , - / L W
Months	1-12, case-insensitive 3-letter abbreviations ("JAN", "aug", etc.)	* , - /
Weekdays	1-7, case-insensitive 3-letter abbreviations ("MON", "fri", etc.)	* , - / L #

Note

Days of the week go from 1 = Sunday to 7 = Saturday, which is different on some other cron systems (where 0 = Sunday and 6 = Saturday). To avoid ambiguity you may prefer to use the three latter abbreviations (e.g. SUN rather than 1).

Examples

Some common time intervals that may be useful for setting up your Cron Trigger:

• * * * * *

  • At every minute

• */30 * * * *

  • At every 30th minute

• 45 * * * *

  • On the 45th minute of every hour

• 0 17 * * sun or 0 17 * * 1

  • 17:00 (UTC) on Sunday

• 10 7 * * mon-fri or 10 7 * * 2-6

  • 07:10 (UTC) on weekdays

• 0 15 1 * *

  • 15:00 (UTC) on first day of the month

• 0 18 * * 6L or 0 18 * * friL

  • 18:00 (UTC) on the last Friday of the month

• 59 23 LW * *

  • 23:59 (UTC) on the last weekday of the month

Test Cron Triggers

The recommended way of testing Cron Triggers is using Wrangler.

Cron Trigger changes take time to propagate.

Changes such as adding a new Cron Trigger, updating an old Cron Trigger, or deleting a Cron Trigger may take several minutes (up to 15 minutes) to propagate to the Cloudflare global network.

Test Cron Triggers using Wrangler by passing in the --test-scheduled flag to wrangler dev. This will expose a /__scheduled (or /cdn-cgi/handler/scheduled for Python Workers) route which can be used to test using a HTTP request. To simulate different cron patterns, a cron query parameter can be passed in.

npx wrangler dev --test-scheduled

curl "http://localhost:8787/__scheduled?cron=*+*+*+*+*"

curl "http://localhost:8787/cdn-cgi/handler/scheduled?cron=*+*+*+*+*" # Python Workers

View past events

To view the execution history of Cron Triggers, view Cron Events:

1. Log in to the Cloudflare dashboard ↗ and select your account.
2. In Account Home, go to Workers & Pages.
3. In Overview, select your Worker.
4. Select Settings.
5. Under Trigger Events, select View events.

Cron Events stores the 100 most recent invocations of the Cron scheduled event. Workers Logs also records invocation logs for the Cron Trigger with a longer retention period and a filter & query interface. If you are interested in an API to access Cron Events, use Cloudflare's GraphQL Analytics API.

Note

It can take up to 30 minutes before events are displayed in Past Cron Events when creating a new Worker or changing a Worker's name.

Refer to Metrics and Analytics for more information.

Remove a Cron Trigger

Via the dashboard

To delete a Cron Trigger on a deployed Worker via the dashboard:

1. Log in to the Cloudflare dashboard ↗ and select your account.
2. Go to Workers & Pages, and select your Worker.
3. Go to Triggers > select the three dot icon next to the Cron Trigger you want to remove > Delete.

Note

You can only delete Cron Triggers using the Cloudflare dashboard (and not through your Wrangler file).

Limits

Refer to Limits to track the maximum number of Cron Triggers per Worker.

Green Compute

With Green Compute enabled, your Cron Triggers will only run on Cloudflare points of presence that are located in data centers that are powered purely by renewable energy. Organizations may claim that they are powered by 100 percent renewable energy if they have procured sufficient renewable energy to account for their overall energy use.

Renewable energy can be purchased in a number of ways, including through on-site generation (wind turbines, solar panels), directly from renewable energy producers through contractual agreements called Power Purchase Agreements (PPA), or in the form of Renewable Energy Credits (REC, IRECs, GoOs) from an energy credit market.

Green Compute can be configured at the account level:

1. Log in to the Cloudflare dashboard ↗ and select your account.
2. In Account Home, select Workers & Pages.
3. In the Account details section, find Compute Setting.
4. Select Change.
5. Select Green Compute.
6. Select Confirm.

Related resources

• Triggers - Review Wrangler configuration file syntax for Cron Triggers.
• Learn how to access Cron Triggers in ES modules syntax for an optimized experience.