Cron Jobs & Scheduled Workers

Every Worker you've written so far responds to an incoming HTTP request. But what if you want code to run on a schedule — no request needed? That's what Cron Triggers do. They turn your Worker into a serverless cron job: fetch data every hour, clean up stale records nightly, warm a cache at 6 AM.

What Are Cron Triggers?

A Cron Trigger is a scheduled invocation of your Worker. Cloudflare calls your Worker at the times you specify — no incoming HTTP request required. Your Worker wakes up, does its work, and goes back to sleep.

Common use cases:

• Data aggregation — Fetch from an external API every hour and cache the result
• Health checks — Ping your services every 5 minutes and alert on failure
• Cache warming — Pre-compute expensive responses before users request them
• Cleanup jobs — Delete expired records or rotate logs nightly

The Cron Syntax

Cloudflare uses standard 5-field cron syntax:

┌───────────── minute (0–59)
│ ┌─────────── hour (0–23)
│ │ ┌───────── day of month (1–31)
│ │ │ ┌─────── month (1–12)
│ │ │ │ ┌───── day of week (0–6, Sunday = 0)
│ │ │ │ │
* * * * *

Examples:

Adding a Cron Trigger

In your wrangler.jsonc, add a triggers block with one or more cron expressions:

{
  "name": "quote-collector",
  "main": "src/index.js",
  "compatibility_date": "2024-01-01",

  // KV namespace for storing fetched quotes
  "kv_namespaces": [
    { "binding": "QUOTES", "id": "your-kv-namespace-id" }
  ],

  // Schedule: run every hour on the hour
  "triggers": {
    "crons": ["0 * * * *"]
  }
}

You can specify multiple schedules if needed:

"triggers": {
  "crons": ["0 * * * *", "0 6 * * *", "0 0 * * 1"]
}

The scheduled Event Handler

HTTP requests hit your fetch handler. Cron invocations hit a different handler: scheduled.

export default {
  // Called by HTTP requests (GET, POST, etc.)
  async fetch(request, env, ctx) {
    // ...
  },

  // Called by Cron Triggers on schedule
  async scheduled(event, env, ctx) {
    // event.cron — the cron pattern that triggered this (e.g., "0 * * * *")
    // event.scheduledTime — the time this was scheduled to run (ms timestamp)
    // env — your bindings (KV, D1, secrets, etc.)
    // ctx.waitUntil() — keep the Worker alive for async work
  }
};

Practical Example: Hourly Quote Collector

Let's build a Worker that runs every hour, fetches a random quote from a public API, and stores it in KV. It also exposes a fetch handler so you (or your frontend) can retrieve the latest quote via HTTP.

Step 1: Create the Project

npx wrangler init quote-collector
cd quote-collector

Step 2: Create the KV Namespace

npx wrangler kv namespace create QUOTES

Copy the output ID into your wrangler.jsonc.

Step 3: Configure wrangler.jsonc

{
  "name": "quote-collector",
  "main": "src/index.js",
  "compatibility_date": "2024-01-01",
  "kv_namespaces": [
    { "binding": "QUOTES", "id": "paste-your-id-here" }
  ],
  "triggers": {
    "crons": ["0 * * * *"]
  }
}

Step 4: Write the Worker

// src/index.js

export default {
  // HTTP handler — returns the latest stored quote
  async fetch(request, env) {
    const url = new URL(request.url);

    if (url.pathname === "/quote") {
      const data = await env.QUOTES.get("latest", { type: "json" });

      if (!data) {
        return new Response(
          JSON.stringify({ error: "No quote stored yet. Wait for the next cron run." }),
          { status: 404, headers: { "Content-Type": "application/json" } }
        );
      }

      return new Response(JSON.stringify(data), {
        headers: { "Content-Type": "application/json" }
      });
    }

    return new Response("Quote Collector API\n\nGET /quote — latest stored quote", {
      headers: { "Content-Type": "text/plain" }
    });
  },

  // Cron handler — fetches a new quote and stores it in KV
  async scheduled(event, env, ctx) {
    ctx.waitUntil(fetchAndStoreQuote(env));
  }
};

async function fetchAndStoreQuote(env) {
  // Using ZenQuotes API (free, no auth required)
  const response = await fetch("https://zenquotes.io/api/random");

  if (!response.ok) {
    console.error(`Quote API returned ${response.status}`);
    return;
  }

  const [quote] = await response.json();

  const data = {
    text: quote.q,
    author: quote.a,
    fetchedAt: new Date().toISOString()
  };

  await env.QUOTES.put("latest", JSON.stringify(data));
  console.log(`Stored quote: "${data.text}" — ${data.author}`);
}

Testing Locally

Start the dev server with the --test-scheduled flag to enable local cron testing:

npx wrangler dev --test-scheduled

Now you can trigger the scheduled handler manually by hitting a special endpoint:

# Trigger the cron handler
curl "http://localhost:8787/__scheduled?cron=0+*+*+*+*"

# Then fetch the stored quote via your HTTP handler
curl "http://localhost:8787/quote"

The /__scheduled endpoint simulates a cron invocation locally. Your scheduled handler runs, fetches the quote, and stores it in the local KV emulator. Then your fetch handler can read it back.

Deploying

Deploy like any other Worker:

npx wrangler deploy

That's it. Once deployed, Cloudflare reads the triggers.crons config and immediately starts scheduling your Worker. No additional setup, no separate cron service, no server to maintain.

You'll see your Worker listed in the Cloudflare dashboard with a "Triggers" tab showing the active cron schedules.

Viewing Logs

After your cron fires in production, you can see what happened:

1. Go to Workers & Pages in the Cloudflare dashboard
2. Click your Worker (quote-collector)
3. Click the Logs tab
4. Select "Begin log stream" for real-time logs, or check "Past logs"

Your console.log() statements from the scheduled handler show up here, along with any errors. You can also tail logs from the CLI:

npx wrangler tail

This streams live logs from your deployed Worker — both HTTP requests and cron invocations.

Complete Final Code

Here's the full Worker in one block for easy reference:

// src/index.js — Quote Collector Worker
// Cron: fetches a random quote every hour and stores in KV
// HTTP: serves the latest quote at GET /quote

export default {
  async fetch(request, env) {
    const url = new URL(request.url);

    if (url.pathname === "/quote") {
      const data = await env.QUOTES.get("latest", { type: "json" });

      if (!data) {
        return new Response(
          JSON.stringify({ error: "No quote stored yet. Wait for the next cron run." }),
          { status: 404, headers: { "Content-Type": "application/json" } }
        );
      }

      return new Response(JSON.stringify(data), {
        headers: {
          "Content-Type": "application/json",
          "Cache-Control": "public, max-age=300"
        }
      });
    }

    if (url.pathname === "/") {
      return new Response(
        "Quote Collector API\n\nGET /quote — returns the latest stored quote\n",
        { headers: { "Content-Type": "text/plain" } }
      );
    }

    return new Response("Not found", { status: 404 });
  },

  async scheduled(event, env, ctx) {
    ctx.waitUntil(fetchAndStoreQuote(env));
  }
};

async function fetchAndStoreQuote(env) {
  const response = await fetch("https://zenquotes.io/api/random");

  if (!response.ok) {
    console.error(`Quote API failed: ${response.status} ${response.statusText}`);
    return;
  }

  const [quote] = await response.json();

  const data = {
    text: quote.q,
    author: quote.a,
    fetchedAt: new Date().toISOString()
  };

  await env.QUOTES.put("latest", JSON.stringify(data));
  console.log(`Stored quote: "${data.text}" — ${data.author}`);
}

And the configuration:

// wrangler.jsonc
{
  "name": "quote-collector",
  "main": "src/index.js",
  "compatibility_date": "2024-01-01",
  "kv_namespaces": [
    { "binding": "QUOTES", "id": "your-kv-namespace-id" }
  ],
  "triggers": {
    "crons": ["0 * * * *"]
  }
}

Knowledge Check

What's Next

You now have the full picture of what Cloudflare Workers can do on the free tier: HTTP APIs, SQL databases, key-value storage, object storage, and now scheduled background jobs — all without a server.

Time to build something real. Go back to Lesson 1's project table and pick one:

• URL shortener — Workers + KV (great starter project)
• Webhook processor — Workers + Queues + D1 (uses cron for retry/cleanup)
• Image hosting — Workers + R2 (zero egress serving)
• Full-stack web app — Workers + D1 + Static Assets (put it all together)

Each project uses concepts from these five lessons. Pick one that interests you and build it end to end.