Skip to content

Run a function on a schedule ​

A cron runs one target on a schedule: a function runtime, a cache invalidation, a promote of the newest ready deployment, or a cron.fired event for your webhooks. This page creates a nightly report job and shows how to check, watch, pause and run it.

A cron that runs a function does not change the live site by itself. A cron whose target is promote_latest or invalidate does, every time it runs.

Throughout, the distribution is acme-marketing (d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38) and the function runtime is 01JBQZ8XKT4A9WN2CDEFGH5RM7. The function should already handle a job event; see Test a function as a background job.

1. Check the schedule ​

Before creating anything, see when the schedule would run.

text
When would "0 2 * * *" in Asia/Tokyo run on acme-marketing? Show me the next five times.
bash
edge crons check acme-marketing --schedule '0 2 * * *' --tz Asia/Tokyo
bash
curl -s -X POST https://api.edge.deca-dev.com/v1/distributions/d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38/crons/check \
  -H "Authorization: Bearer $EDGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"schedule": "0 2 * * *", "timezone": "Asia/Tokyo"}'

The agent runs edge_cron_check. Each run comes back in UTC and in Tokyo time:

json
{
  "schedule": "0 2 * * *",
  "timezone": "Asia/Tokyo",
  "next_runs": [
    { "at": "2026-10-19T17:00:00+00:00", "local": "2026-10-20T02:00:00+09:00" },
    …
  ]
}

Cron syntax has the fields, aliases and time zone rules.

2. Create the cron ​

text
On acme-marketing, create a cron named nightly-report that runs function
01JBQZ8XKT4A9WN2CDEFGH5RM7 at 02:00 Tokyo time every day, retrying once if it fails.
bash
edge crons create acme-marketing --name nightly-report --schedule '0 2 * * *' \
  --tz Asia/Tokyo --function 01JBQZ8XKT4A9WN2CDEFGH5RM7 --retries 1
bash
curl -s -X POST https://api.edge.deca-dev.com/v1/distributions/d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38/crons \
  -H "Authorization: Bearer $EDGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "nightly-report",
        "schedule": "0 2 * * *",
        "timezone": "Asia/Tokyo",
        "target": {"type": "wasm", "script_id": "01JBQZ8XKT4A9WN2CDEFGH5RM7"},
        "retries": 1
      }'

The agent runs edge_cron_create. The answer has the cron_id and when it runs next:

json
{
  "cron_id": "crn_01M4XA2B3C4D5E6F7G8H9J0K1M",
  "name": "nightly-report",
  "enabled": true,
  "next_run_at": "2026-10-19T17:00:00+00:00",
  "next_run_local": "2026-10-20T02:00:00+09:00",
  …
}

Each run sends your function a POST to /_jobs/cron/nightly-report on the background runner, with up to the function's background timeout to finish.

By default a run is skipped if the previous one is still going; set overlap to allow to let them run side by side. Other targets: --emit (a cron.fired event), --invalidate /news/* (refresh cached paths), --promote-latest, --enqueue orders (send one message to a queue), and --start-workflow 01JBQZ8XKT4A9WN2CDEFGH5RM7 (start a workflow run).

3. Watch it run ​

In the web app, open Distributions and select acme-marketing. Crons shows each cron's schedule, its next run in its own time zone, and how the last run ended. Background jobs lists the runs themselves.

text
Show me the last runs of the nightly-report cron on acme-marketing.
bash
edge crons runs crn_01M4XA2B3C4D5E6F7G8H9J0K1M
bash
curl -s https://api.edge.deca-dev.com/v1/crons/crn_01M4XA2B3C4D5E6F7G8H9J0K1M/runs \
  -H "Authorization: Bearer $EDGE_TOKEN"

The agent runs edge_cron_runs. A run's status is queued, running, succeeded, failed, skipped (the previous run was still going) or missed (Edge reached it more than a day late). A failed run that can be retried runs again 30 seconds later, then 2 minutes, then 10 minutes, up to the cron's retries.

4. Run it now, pause it, resume it ​

In the web app, the Crons list has Run now and Pause / Resume. Run now queues one run immediately and leaves the schedule alone.

text
Run the nightly-report cron now, then pause it.
bash
edge crons trigger crn_01M4XA2B3C4D5E6F7G8H9J0K1M
edge crons update crn_01M4XA2B3C4D5E6F7G8H9J0K1M --enabled false
bash
curl -s -X POST https://api.edge.deca-dev.com/v1/crons/crn_01M4XA2B3C4D5E6F7G8H9J0K1M/trigger \
  -H "Authorization: Bearer $EDGE_TOKEN"
curl -s -X PATCH https://api.edge.deca-dev.com/v1/crons/crn_01M4XA2B3C4D5E6F7G8H9J0K1M \
  -H "Authorization: Bearer $EDGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

The agent runs edge_cron_trigger and edge_cron_update. A paused cron has no next run; resuming it schedules the next one from now. It does not catch up on the runs it skipped while paused.

5. Hear about failures ​

Subscribe a webhook to cron.run.failed (a run failed with no retries left) and cron.run.missed. See Send events to a webhook.

Next ​

Read Background jobs for why a run can happen twice and how to make your function safe to run again.