Cloudflare Workflows

Workflows provide durable multi-step execution for Workers. Steps persist state, survive restarts, support retries, and can sleep for days.

---

Quick Start

Create Workflow

// src/index.ts
import { WorkflowEntrypoint, WorkflowStep, WorkflowEvent } from "cloudflare:workers";

interface Env {
  MY_WORKFLOW: Workflow;
}

interface Params {
  userId: string;
  action: string;
}

export class MyWorkflow extends WorkflowEntrypoint<Env, Params> {
  async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
    const user = await step.do("fetch user", async () => {
      const resp = await fetch(`https://api.example.com/users/${event.payload.userId}`);
      return resp.json();
    });

    await step.sleep("wait before processing", "1 hour");

    const result = await step.do("process action", async () => {
      return { processed: true, user: user.id };
    });

    return result; // Available in instance.status().output
  }
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const instance = await env.MY_WORKFLOW.create({
      params: { userId: "123", action: "activate" },
    });
    return Response.json({ instanceId: instance.id });
  },
};

wrangler.jsonc

{
  "name": "my-workflow-worker",
  "main": "src/index.ts",
  "workflows": [
    {
      "name": "my-workflow",
      "binding": "MY_WORKFLOW",
      "class_name": "MyWorkflow"
    }
  ]
}

Deploy

npx wrangler deploy

---

Core Concepts

WorkflowEntrypoint

export class MyWorkflow extends WorkflowEntrypoint<Env, Params> {
  async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
    // Workflow logic with steps
    return optionalResult;
  }
}

WorkflowEvent

interface WorkflowEvent<T> {
  payload: Readonly<T>; // Immutable input params
  timestamp: Date; // Creation time
  instanceId: string; // Unique instance ID
}

Warning: Event payload is immutable. Changes are NOT persisted across steps. Return state from steps instead.

WorkflowStep

interface WorkflowStep {
  do<T>(name: string, callback: () => Promise<T>): Promise<T>;
  do<T>(name: string, config: StepConfig, callback: () => Promise<T>): Promise<T>;
  sleep(name: string, duration: Duration): Promise<void>;
  sleepUntil(name: string, timestamp: Date | number): Promise<void>;
  waitForEvent<T>(name: string, options: WaitOptions): Promise<T>;
}

See api.md for full type definitions.

---

Steps

Basic Step

const result = await step.do("step name", async () => {
  const response = await fetch("https://api.example.com/data");
  return response.json(); // State persisted
});

Step with Config

const data = await step.do(
  "call external API",
  {
    retries: {
      limit: 10,
      delay: "30 seconds",
      backoff: "exponential",
    },
    timeout: "5 minutes",
  },
  async () => {
    return await externalApiCall();
  }
);

Default Step Config

const defaultConfig = {
  retries: {
    limit: 5,
    delay: 10000, // 10 seconds
    backoff: "exponential",
  },
  timeout: "10 minutes",
};

Option	Type	Default	Description
retries.limit	number	5	Max attempts (use Infinity for unlimited)
retries.delay	string/number	10000	Delay between retries
retries.backoff	string	exponential	constant, linear, exponential
timeout	string/number	10 min	Per-attempt timeout

---

Sleep & Scheduling

Relative Sleep

await step.sleep("wait before retry", "1 hour");
await step.sleep("short pause", 5000); // 5 seconds (ms)

Duration units: second, minute, hour, day, week, month, year.

Sleep Until Date

const targetDate = new Date("2024-12-31T00:00:00Z");
await step.sleepUntil("wait until new year", targetDate);

// Or with timestamp
await step.sleepUntil("wait until launch", Date.parse("24 Oct 2024 13:00:00 UTC"));

Maximum sleep: 365 days.

Note: step.sleep and step.sleepUntil do NOT count towards the 1024 steps limit.

---

Wait for Events

Wait in Workflow

const approval = await step.waitForEvent<{ approved: boolean }>("wait for approval", {
  type: "user_approval",
  timeout: "7 days",
});

if (approval.approved) {
  await step.do("proceed", async () => {
    /* ... */
  });
}

Default timeout: 24 hours.

Timeout behavior: Throws error and fails instance. Use try-catch to continue:

try {
  const event = await step.waitForEvent("optional event", { type: "update", timeout: "1 hour" });
} catch (e) {
  // Continue without event
}

Send Event from Worker

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const { instanceId, approved } = await request.json();
    const instance = await env.MY_WORKFLOW.get(instanceId);

    await instance.sendEvent({
      type: "user_approval", // Must match waitForEvent type
      payload: { approved },
    });

    return new Response("Event sent");
  },
};

Event buffering: Events can be sent before Workflow reaches waitForEvent. They are buffered and delivered when the matching step executes.

See events.md for REST API.

---

Error Handling

NonRetryableError

import { NonRetryableError } from "cloudflare:workflows";

await step.do("validate input", async () => {
  if (!event.payload.data) {
    throw new NonRetryableError("Missing required data");
  }
  return event.payload.data;
});

Catch and Continue

try {
  await step.do("risky operation", async () => {
    await riskyApiCall();
  });
} catch (error) {
  await step.do("handle failure", async () => {
    await sendAlertEmail(error.message);
  });
}

Workflow States

Status	Description
queued	Waiting to start
running	Actively executing
paused	Manually paused
waiting	Sleeping or waiting for event
waitingForPause	Pause requested, waiting to take effect
complete	Successfully finished
errored	Failed (uncaught exception or retry limit)
terminated	Manually terminated

---

Workflow Bindings

Create Instance

const instance = await env.MY_WORKFLOW.create({
  id: "order-12345", // Optional custom ID (max 100 chars)
  params: { orderId: 12345 },
});
console.log(instance.id);

Create Batch

const instances = await env.MY_WORKFLOW.createBatch([{ params: { userId: "1" } }, { params: { userId: "2" } }, { params: { userId: "3" } }]);
// Up to 100 instances per batch

Get Instance

const instance = await env.MY_WORKFLOW.get("order-12345");

Instance Methods

await instance.pause(); // Pause execution
await instance.resume(); // Resume paused
await instance.terminate(); // Stop permanently
await instance.restart(); // Restart from beginning

const status = await instance.status();
console.log(status.status); // "running", "complete", etc.
console.log(status.output); // Return value from run()
console.log(status.error); // { name, message } if errored

await instance.sendEvent({
  type: "approval",
  payload: { approved: true },
});

---

Rules of Workflows

✅ DO

• Make steps granular and self-contained
• Return state from steps (only way to persist)
• Name steps deterministically
• await all step calls
• Keep step return values under 1 MiB
• Use idempotent operations in steps
• Base conditions on event.payload or step returns

❌ DON'T

• Store state outside steps (lost on restart)
• Mutate event.payload (changes not persisted)
• Use non-deterministic step names (Date.now(), Math.random())
• Skip await on step calls
• Put entire logic in one step
• Call multiple unrelated services in one step
• Do heavy CPU work in single step

Step State Persistence

// ✅ Good: Return state from step
const userData = await step.do("fetch user", async () => {
  return await fetchUser(userId);
});

// ❌ Bad: State stored outside step (lost on restart)
let userData;
await step.do("fetch user", async () => {
  userData = await fetchUser(userId); // Will be lost!
});

---

Wrangler Commands

# List instances
wrangler workflows instances list my-workflow

# Describe instance
wrangler workflows instances describe my-workflow --id <instance-id>

# Terminate instance
wrangler workflows instances terminate my-workflow --id <instance-id>

# Trigger new instance
wrangler workflows trigger my-workflow --params '{"key": "value"}'

# Delete Workflow
wrangler workflows delete my-workflow

---

Limits

Feature	Free	Paid
CPU time per step	10 ms	30 sec (max 5 min)
Wall clock per step	Unlimited	Unlimited
State per step	1 MiB	1 MiB
Event payload	1 MiB	1 MiB
Total state per instance	100 MB	1 GB
Max sleep duration	365 days	365 days
Max steps per Workflow	1024	1024
Concurrent instances	25	10,000
Instance creation rate	100/sec	100/sec
Queued instances	100,000	1,000,000
Subrequests per instance	50/req	1000/req
Instance ID length	100 chars	100 chars
Retention (completed)	3 days	30 days

Note: Instances in waiting state (sleeping, waiting for event) do NOT count against concurrency limits.

Increase CPU Limit

{
  "limits": {
    "cpu_ms": 300000 // 5 minutes
  }
}

---

Pricing

Based on Workers Standard pricing:

Metric	Free	Paid
Requests	100K/day (shared)	10M/mo included, +$0.30/M
CPU time	10 ms/invocation	30M ms/mo included, +$0.02/M ms
Storage	1 GB	1 GB included, +$0.20/GB-mo

Storage notes:

• Calculated across all instances (running, sleeping, completed)
• Deleting instances frees storage (updates within minutes)
• Free plan: instance errors if storage limit reached

See pricing.md for details.

---

Prohibitions

• ❌ Do not mutate event.payload (changes not persisted)
• ❌ Do not store state outside steps
• ❌ Do not use non-deterministic step names
• ❌ Do not exceed 1 MiB per step return
• ❌ Do not skip await on step calls
• ❌ Do not rely on in-memory state between steps

---

References

• api.md — Full API reference
• events.md — Event handling and REST API
• patterns.md — Saga, approval, reminders
• pricing.md — Billing details

Cross-References (Skills)

• cloudflare-workers — Worker development
• cloudflare-queues — Message queue integration
• cloudflare-r2 — Large state storage
• cloudflare-kv — Key-value references