# Cron Heartbeat (/experiments/cron-heartbeat)



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 Endpoint [#api-endpoint]

### GET /status [#get-status]

Returns metadata from the most recent scheduled run.

#### Example Request [#example-request]

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

#### Response Fields [#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 [#example-response]

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

<Callout>
  Before the first cron fires, `lastRun` and `lastCron` are `null` and `runCount` is `0`.
</Callout>

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

## Deployment [#deployment]

<Steps>
  <Step>
    ### Click the deploy button [#click-the-deploy-button]

    [![Deploy to Cloudflare Workers](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/shrinathsnayak/cloudflare-experiments/tree/main/apps/experiments/cron-heartbeat)
  </Step>

  <Step>
    ### Create KV namespace [#create-kv-namespace]

    Update `wrangler.json` with your KV namespace ID for the `STATUS` binding.
  </Step>

  <Step>
    ### Check status [#check-status]

    ```bash
    curl "https://your-worker.workers.dev/status"
    ```
  </Step>
</Steps>

## Local Development [#local-development]

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

Trigger a cron manually in local dev:

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

## Configuration [#configuration]

`wrangler.json` declares:

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

## Cloudflare Features Used [#cloudflare-features-used]

* [Cron Triggers](https://developers.cloudflare.com/workers/configuration/cron-triggers/) - scheduled Worker invocations
* [Workers KV](https://developers.cloudflare.com/kv/) - persist run metadata across invocations