In Cloudflare Workflows, how do you define a workflow and start an instance of it from a Worker?
answer
- a class with one method
- extends WorkflowEntrypoint
- a workflows entry in the Wrangler file
- create with id and params
- get(id) then status()
basics
~20 sExport a class that extends WorkflowEntrypoint and implements run(event, step), declare it under workflows in the Wrangler file, then call env.BINDING.create({ id, params }) from a Worker; the instance runs its steps durably in the background.
solid answer
~40 sA Workflow is a class that extends `WorkflowEntrypoint` from `cloudflare:workers` and implements `run(event, step)`, with each unit of work inside a `step.do()` call. The Wrangler file declares it under `workflows` with a `name`, the `binding` the Worker sees on `env`, and the exported `class_name`. A Worker starts a run with `await env.ONBOARDING.create({ id, params })`: `params` arrives in `run()` as `event.payload`, and the call returns a `WorkflowInstance` handle at once while the steps run in the background. Later, `env.ONBOARDING.get(id)` returns a handle whose `status()` reports the state (`queued`, `running`, `waiting`, `complete`, `errored` and others) and the value `run()` returned. Leave out `id` and Workflows generates one; supply it and it must be unique within that Workflow.
code
json · 8 lines{
"name": "onboarding-worker",
"main": "src/index.js",
"compatibility_date": "2026-10-10",
"workflows": [
{ "name": "onboarding", "binding": "ONBOARDING", "class_name": "OnboardingWorkflow" }
]
}go deeper
Recall the three pieces: a class extending WorkflowEntrypoint with run(event, step), a workflows binding with name, binding and class_name, and env.BINDING.create({ id, params }) to start an instance.
Explain that create() returns a handle immediately while steps run in the background, how params becomes event.payload, and how get(id) and status() report state and output.
Show you design instance IDs deliberately: unique per run, composite when tied to a user, and aware that create() throws on a retained duplicate while createBatch() skips it instead.
Frame the trigger as a contract between teams: who owns the Workflow's Worker, which callers bind to it through script_name, and how instance IDs map back to business records.
## What a Workflow is on Cloudflare **Cloudflare Workflows** is the platform's durable-execution product. A Workflow is ordinary Worker code split into **steps**: the platform persists the result of each step, retries a step that throws, and can pause an instance for minutes or months between steps. One deployed Workflow definition can have many **instances**, one per run, each with its own ID, input and state. In the onboarding example used here, every new sign-up gets its own instance that creates the account, sends a welcome email, waits for email verification and later starts billing. ## The three pieces A working Workflow needs three things, all in one Worker project: 1. **The class.** Export a class that extends `WorkflowEntrypoint`, imported from `cloudflare:workers`, and implement `async run(event, step)`. The docs require at least one `step` call for it to count as a valid Workflow. Whatever `run()` returns becomes the instance's `output` in its status. 2. **The binding.** Add an entry to the `workflows` array in the Wrangler file with `name` (the Workflow's name in the account, up to 64 characters), `binding` (the property on `env`) and `class_name` (the exported class). Wrangler creates or updates the Workflow when you run `wrangler deploy`. 3. **The trigger.** Code that holds the binding calls `env.ONBOARDING.create()` to start an instance and `env.ONBOARDING.get(id)` to reach an existing one. The binding is what makes the call safe and simple: no API token or HTTP client sits in the Worker, the same way a KV or R2 binding needs none. ## The event your run() receives | Field of `event` | What it holds | |---|---| | `payload` | The `params` passed to `create()`, read-only | | `timestamp` | A `Date` for when the instance was created | | `instanceId` | The instance's ID | | `workflowName` | The Workflow's `name` from the binding | | `schedule` | Cron metadata, only for instances started by a schedule | Treat `event.payload` as immutable. Changes you make to it are not persisted across steps or restarts; data a later step needs is passed by **returning it from a step**. ## Instance IDs and inputs - `create()` accepts an optional `id` of up to 100 characters (letters, digits, `-` and `_`). Without one, Workflows generates an ID. - An ID must be unique within the Workflow. `create()` **throws** when an instance with that ID still exists inside its retention period, which by default is 3 days on Workers Free and 30 days on Workers Paid. To run the same ID again, call `restart()` on the existing instance. - A per-user ID such as the bare user ID is a trap: the user's second run collides with the first. The docs suggest a transaction-style ID or a composite such as the user ID plus a random suffix, with the mapping stored in a database. - `params` must be JSON-serializable and at most 1 MiB. - `createBatch()` starts up to 100 instances in one call and, unlike `create()`, skips a duplicate ID instead of throwing. ## Checking on an instance `env.ONBOARDING.get(id)` returns a `WorkflowInstance` handle for an existing ID and throws when the ID does not exist, so a status route should catch that and answer with a 404 or 400. The handle's `status()` resolves to an object with: - `status`: one of `queued` (waiting for a concurrency slot), `running`, `paused`, `waiting` (sleeping, waiting to retry or waiting for an event), `waitingForPause`, `complete`, `errored`, `terminated` or `unknown`. - `output`: the value `run()` returned, once the instance is `complete`. - `error`: the `name` and `message` of the error that ended an `errored` instance. The same handle carries the operator methods `pause()`, `resume()`, `terminate()`, `restart()` and `sendEvent()`. Returning `instance.id` from the trigger route, as the example does, gives the caller the key it needs for every one of them later. ## Other ways to start an instance - `wrangler workflows trigger onboarding '{"email":"[email protected]"}'` starts one from the command line, with `--id` for a custom ID. - A `schedules` cron list on the binding starts instances on a timetable. - The REST API and, from another Worker, a `workflows` binding with `script_name` pointing at the Worker that defines the class. Starting an instance is asynchronous: `create()` resolves once the instance is accepted, not when it finishes. A caller that needs the result polls `status()` until the instance is `complete`.
- What happens if you call create() twice with the same instance ID?The second call throws, because an ID must be unique within the Workflow while the first instance's state is still retained (by default 3 days on Workers Free, 30 days on Workers Paid). To run that ID again, call `restart()` on the existing instance, or use a composite ID such as the user ID plus a random suffix. `createBatch()` differs: it skips the duplicate instead of throwing.
- Can a Worker that does not contain the Workflow class still start it?Yes. Give that Worker its own `workflows` binding with `script_name` set to the Worker that exports the class, plus the same `name` and `class_name`. It then calls `create()` and `get()` on its binding exactly as the defining Worker would, so a public API Worker can start a Workflow that a separate background Worker deploys.
- A Workflow is a handler you add to export default, like fetch or scheduled.
- create() waits for every step to finish and returns the Workflow's result.
- Changing event.payload inside run() passes the new value to later steps.
- Reusing an instance ID just replaces the earlier run of that ID.
- The calling Worker needs an API token to start a Workflow instance.