Cron Heartbeat

Reference implementation for Cron Triggers - scheduled tasks with run metadata stored in KV

A minimal reference for Cron Triggers: a scheduled() handler runs every 5 minutes and writes run metadata to Workers KV. An HTTP route reads that metadata back.

API Reference

GET /status

Returns metadata from the most recent scheduled run.

Example Request

curl "https://your-worker.workers.dev/status"

Response Fields

lastRun string | null

ISO timestamp of the last cron execution.

lastCron string | null

Cron expression that fired (e.g. */5 * * * *).

runCount number

Total scheduled runs since deploy.

Example Response

{
  "lastRun": "2025-06-20T12:00:00.000Z",
  "lastCron": "*/5 * * * *",
  "runCount": 12
}

Before the first cron fires, lastRun and lastCron are null and runCount is 0.

Use Cases

Learn how to implement a scheduled() handler in Workers
Periodic health checks, cache warming, or cleanup jobs
Background maintenance without external cron services
Storing cron run history in KV for observability

Limitations

Cron schedule is fixed in wrangler.json; change and redeploy to adjust timing
Stores last-run metadata in KV only; not a full job scheduler
Demonstration worker; no alerting or retry logic on failed runs

Deployment

Click the deploy button

Create KV namespace

Update wrangler.json with your KV namespace ID for the STATUS binding.

Check status

curl "https://your-worker.workers.dev/status"

Local Development

cd apps/experiments/cron-heartbeat
npm install
npm run dev

Trigger a cron manually in local dev:

curl "http://localhost:8787/cdn-cgi/handler/scheduled"

Configuration

wrangler.json declares:

Cron trigger */5 * * * * (every 5 minutes)
KV binding STATUS for run metadata

Cloudflare Features Used

Workers - Edge compute runtime
Cron Triggers - scheduled Worker invocations
Workers KV - persist run metadata across invocations

Cron Heartbeat

On this page