Cron Triggers
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.
Cron Triggers execute on UTC time.
To respond to a Cron Trigger, you must add a "scheduled"
handler to your Worker.
Refer to the following examples to write your code:
After you have updated your Worker code to include a "scheduled"
event, you must update your Worker project configuration.
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:
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:
To add Cron Triggers in the Cloudflare dashboard:
- Log in to the Cloudflare dashboard ↗ and select your account.
- In Account Home, select Workers & Pages.
- In Overview, select your Worker > Settings > Triggers > Cron Triggers.
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 # |
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
or0 17 * * 1
- 5PM on Sunday
-
10 7 * * mon-fri
or10 7 * * 2-6
- 7:10AM on weekdays
-
0 15 1 * *
- 3PM on first day of the month
-
0 18 * * 6L
or0 18 * * friL
- 6PM on the last Friday of the month
-
59 23 LW * *
- 11:59PM on the last weekday of the month
The recommended way of testing Cron Triggers is using Wrangler.
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.
To view the execution history of Cron Triggers, view Cron Events:
- Log in to the Cloudflare dashboard ↗ and select your account.
- In Account Home, go to Workers & Pages.
- In Overview, select your Worker.
- Select Settings.
- 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.
Refer to Metrics and Analytics for more information.
To delete a Cron Trigger on a deployed Worker via the dashboard:
- Log in to the Cloudflare dashboard ↗ and select your account.
- Go to Workers & Pages, and select your Worker.
- Go to Triggers > select the three dot icon next to the Cron Trigger you want to remove > Delete.
Refer to Limits to track the maximum number of Cron Triggers per Worker.
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:
- Log in to the Cloudflare dashboard ↗ and select your account.
- In Account Home, select Workers & Pages.
- In the Account details section, find Compute Setting.
- Select Change.
- Select Green Compute.
- Select Confirm.
- Triggers - Review
wrangler.toml
syntax for Cron Triggers. - Learn how to access Cron Triggers in ES modules syntax for an optimized experience.