1# Cron Triggers API
2 
3## Basic Handler
4 
5```typescript
6export default {
7  async scheduled(controller: ScheduledController, env: Env, ctx: ExecutionContext): Promise<void> {
8    console.log("Cron executed:", new Date(controller.scheduledTime));
9  },
10};
11```
12 
13**JavaScript:** Same signature without types  
14**Python:** `class Default(WorkerEntrypoint): async def scheduled(self, controller, env, ctx)`
15 
16## ScheduledController
17 
18```typescript
19interface ScheduledController {
20  scheduledTime: number;  // Unix ms when scheduled to run
21  cron: string;           // Expression that triggered (e.g., "*/5 * * * *")
22  type: string;           // Always "scheduled"
23  noRetry(): void;        // Prevent automatic retry on failure
24}
25```
26 
27**Prevent retry on failure:**
28```typescript
29export default {
30  async scheduled(controller, env, ctx) {
31    try {
32      await riskyOperation(env);
33    } catch (error) {
34      // Don't retry - failure is expected/acceptable
35      controller.noRetry();
36      console.error("Operation failed, not retrying:", error);
37    }
38  },
39};
40```
41 
42**When to use noRetry():**
43- External API failures outside your control (avoid hammering failed services)
44- Rate limit errors (retry would fail again immediately)
45- Duplicate execution detected (idempotency check failed)
46- Non-critical operations where skip is acceptable (analytics, caching)
47- Validation errors that won't resolve on retry
48 
49## Handler Parameters
50 
51**`controller: ScheduledController`**
52- Access cron expression and scheduled time
53 
54**`env: Env`**
55- All bindings: KV, R2, D1, secrets, service bindings
56 
57**`ctx: ExecutionContext`**
58- `ctx.waitUntil(promise)` - Extend execution for async tasks (logging, cleanup, external APIs)
59- First `waitUntil` failure recorded in Cron Events
60 
61## Multiple Schedules
62 
63```typescript
64export default {
65  async scheduled(controller, env, ctx) {
66    switch (controller.cron) {
67      case "*/3 * * * *": ctx.waitUntil(updateRecentData(env)); break;
68      case "0 * * * *": ctx.waitUntil(processHourlyAggregation(env)); break;
69      case "0 2 * * *": ctx.waitUntil(performDailyMaintenance(env)); break;
70      default: console.warn(`Unhandled: ${controller.cron}`);
71    }
72  },
73};
74```
75 
76## ctx.waitUntil Usage
77 
78```typescript
79export default {
80  async scheduled(controller, env, ctx) {
81    const data = await fetchCriticalData(); // Critical path
82    
83    // Non-blocking background tasks
84    ctx.waitUntil(Promise.all([
85      logToAnalytics(data),
86      cleanupOldRecords(env.DB),
87      notifyWebhook(env.WEBHOOK_URL, data),
88    ]));
89  },
90};
91```
92 
93## Workflow Integration
94 
95```typescript
96import { WorkflowEntrypoint } from "cloudflare:workers";
97 
98export class DataProcessingWorkflow extends WorkflowEntrypoint {
99  async run(event, step) {
100    const data = await step.do("fetch-data", () => fetchLargeDataset());
101    const processed = await step.do("process-data", () => processDataset(data));
102    await step.do("store-results", () => storeResults(processed));
103  }
104}
105 
106export default {
107  async scheduled(controller, env, ctx) {
108    const instance = await env.MY_WORKFLOW.create({
109      params: { scheduledTime: controller.scheduledTime, cron: controller.cron },
110    });
111    console.log(`Started workflow: ${instance.id}`);
112  },
113};
114```
115 
116## Testing Handler
117 
118**Local development (/__scheduled endpoint):**
119```bash
120# Start dev server
121npx wrangler dev
122 
123# Trigger any cron
124curl "http://localhost:8787/__scheduled?cron=*/5+*+*+*+*"
125 
126# Trigger specific cron with custom time
127curl "http://localhost:8787/__scheduled?cron=0+2+*+*+*&scheduledTime=1704067200000"
128```
129 
130**Query parameters:**
131- `cron` - Required. URL-encoded cron expression (use `+` for spaces)
132- `scheduledTime` - Optional. Unix timestamp in milliseconds (defaults to current time)
133 
134**Production security:** The `/__scheduled` endpoint is available in production and can be triggered by anyone. Block it or implement authentication - see [gotchas.md](./gotchas.md#security-concerns)
135 
136**Unit testing (Vitest):**
137```typescript
138// test/scheduled.test.ts
139import { describe, it, expect } from "vitest";
140import { env } from "cloudflare:test";
141import worker from "../src/index";
142 
143describe("Scheduled Handler", () => {
144  it("processes scheduled event", async () => {
145    const controller = { scheduledTime: Date.now(), cron: "*/5 * * * *", type: "scheduled" as const, noRetry: () => {} };
146    const ctx = { waitUntil: (p: Promise<any>) => p, passThroughOnException: () => {} };
147    await worker.scheduled(controller, env, ctx);
148    expect(await env.MY_KV.get("last_run")).toBeDefined();
149  });
150  
151  it("handles multiple crons", async () => {
152    const ctx = { waitUntil: () => {}, passThroughOnException: () => {} };
153    await worker.scheduled({ scheduledTime: Date.now(), cron: "*/5 * * * *", type: "scheduled", noRetry: () => {} }, env, ctx);
154    expect(await env.MY_KV.get("last_type")).toBe("frequent");
155  });
156});
157```
158 
159## Error Handling
160 
161**Automatic retries:**
162- Failed cron executions are retried automatically unless `noRetry()` is called
163- Retry happens after a delay (typically minutes)
164- Only first `waitUntil()` failure is recorded in Cron Events
165 
166**Best practices:**
167```typescript
168export default {
169  async scheduled(controller, env, ctx) {
170    try {
171      await criticalOperation(env);
172    } catch (error) {
173      // Log error details
174      console.error("Cron failed:", {
175        cron: controller.cron,
176        scheduledTime: controller.scheduledTime,
177        error: error.message,
178        stack: error.stack,
179      });
180      
181      // Decide: retry or skip
182      if (error.message.includes("rate limit")) {
183        controller.noRetry(); // Skip retry for rate limits
184      }
185      // Otherwise allow automatic retry
186      throw error;
187    }
188  },
189};
190```
191 
192## See Also
193 
194- [README.md](./README.md) - Overview
195- [patterns.md](./patterns.md) - Use cases, examples
196- [gotchas.md](./gotchas.md) - Common errors, testing issues
197