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.

Refer to the following 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 wrangler.toml

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

Refer to the example below for a sample wrangler.toml Cron Triggers configuration:

[triggers]
# Schedule cron triggers:
# - At every 3rd minute
# - At 3PM on first day of the month
# - At 11:59PM 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.toml. You need to put the [triggers] table under your chosen environment. For example:

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

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

  • 5PM on Sunday

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

  • 7:10AM on weekdays

• 0 15 1 * *

  • 3PM on first day of the month

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

  • 6PM on the last Friday of the month

• 59 23 LW * *

  • 11:59PM 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 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=*+*+*+*+*"

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.toml 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.toml syntax for Cron Triggers.
• Learn how to access Cron Triggers in ES modules syntax for an optimized experience.