Text of developers.cloudflare.com › workflows › build › workers-api as Styx crawled it on Nov 20, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Workers API · Cloudflare Workflows docs

Skip to content Documentation Index Fetch the complete documentation index at: https://developers.cloudflare.com/workflows/llms.txt Use this file to discover all available pages before exploring further. Workers API This guide details the Workflows API within Cloudflare Workers, including methods, types, and usage examples. WorkflowEntrypoint The WorkflowEntrypoint class is the core element of a Workflow definition. A Workflow must extend this class and define a run method with at least one step call to be considered a valid Workflow. export class MyWorkflow extends WorkflowEntrypoint < Env , Params > { async run ( event : WorkflowEvent < Params >, step : WorkflowStep ) { // Steps here } } run run(event: WorkflowEvent<T>, step: WorkflowStep): Promise<T> event - the event passed to the Workflow, including an optional payload containing data (parameters) step - the WorkflowStep type that provides the step methods for your Workflow The run method can optionally return data, which is available when querying the instance status via the Workers API , REST API and the Workflows dashboard.

This can be useful if your Workflow is computing a result, returning the key to data stored in object storage, or generating some kind of identifier you need to act on. export class MyWorkflow extends WorkflowEntrypoint < Env , Params > { async run ( event : WorkflowEvent < Params >, step : WorkflowStep ) { // Steps here let someComputedState = await step. do ( "my step" , async () => {}); // Optional: return state from our run() method return someComputedState; } } The WorkflowEvent type accepts an optional type parameter ↗︎ that allows you to provide a type for the payload property within the WorkflowEvent .

Refer to the events and parameters documentation for how to handle events within your Workflow code. Finally, any JS control-flow primitive (if conditions, loops, try...catch blocks, promises, and more) can be used to manage steps inside the run method. WorkflowEvent export type WorkflowCronSchedule = { /** Cron expression that triggered this event. */ cron : string ; /** Timestamp of the scheduled trigger, in milliseconds since the Unix epoch. */ scheduledTime : number ; }; export type WorkflowEvent < T > = { payload : Readonly < T >; timestamp : Date ; instanceId : string ; workflowName : string ; schedule ?: WorkflowCronSchedule ; }; The WorkflowEvent is the first argument to a Workflow's run method. payload - a default type of any or type T if a type parameter is provided. timestamp - a Date object set to the time the Workflow instance was created (triggered). instanceId - the ID of the associated instance. workflowName - the name of the associated Workflow. schedule - metadata for Workflow instances created by a cron schedule, including the cron expression and scheduledTime in milliseconds since the Unix epoch.

Refer to the events and parameters documentation for how to handle events within your Workflow code. WorkflowStep step step.do(name: string, callback: (ctx: WorkflowStepContext): RpcSerializable): Promise<T> step.do(name: string, callback: (ctx: WorkflowStepContext): RpcSerializable, rollbackOptions?: WorkflowStepRollbackOptions<T>): Promise<T> step.do(name: string, config?: WorkflowStepConfig, callback: (ctx: WorkflowStepContext): RpcSerializable): Promise<T> name - the name of the step, up to 256 characters. config (optional) - an optional WorkflowStepConfig for configuring step specific retry behaviour . callback - an asynchronous function that receives a WorkflowStepContext and optionally returns serializable state for the Workflow to persist.

In JavaScript Workflows, this includes a fresh, unlocked ReadableStream<Uint8Array> for large binary output. step.do(name: string, config?: WorkflowStepConfig, callback: (ctx: WorkflowStepContext): RpcSerializable, rollbackOptions?: WorkflowStepRollbackOptions<T>): Promise<T> name - the name of the step, up to 256 characters. config (optional) - an optional WorkflowStepConfig for configuring step specific retry behaviour . callback - an asynchronous function that receives a WorkflowStepContext and optionally returns serializable state for the Workflow to persist.

In JavaScript Workflows, this includes a fresh, unlocked ReadableStream<Uint8Array> for large binary output. rollbackOptions (optional) - register rollback logic for the step. If the Workflow later fails, registered rollbacks run in reverse step-start order. After a ReadableStream<Uint8Array> object has been persisted within a step, it should not be reused - rely on the new fresh stream that gets returned from step. The bytes are preserved from the original stream, but the implementation might differ. ::: export class MyWorkflow extends WorkflowEntrypoint { async run ( _event , step ) { const reportStream = await step. do ( "read report from R2" , async () => { const object = await this .env.

MY_BUCKET . get ( "reports/latest.csv" ); if ( ! object?.body) { throw new Error ( "Could not read reports/latest.csv from R2." ); } return object.body; }); const preview = await new Response (reportStream). text (); return { preview }; } } type Env = { MY_BUCKET : R2Bucket ; }; export class MyWorkflow extends WorkflowEntrypoint < Env > { async run ( _event : WorkflowEvent < unknown >, step : WorkflowStep ) { const reportStream = await step. do ( "read report from R2" , async () => { const object = await this .env.

MY_BUCKET . get ( "reports/latest.csv" ); if ( ! object?.body) { throw new Error ( "Could not read reports/latest.csv from R2." ); } return object.body; }); const preview = await new Response (reportStream). text (); return { preview }; } } step.sleep(name: string, duration: WorkflowDuration): Promise<void> name - the name of the step. duration - the duration to sleep for, as a number in milliseconds or as a WorkflowDuration -compatible string.

Refer to the documentation on sleeping and retrying to learn more about how Workflows are retried. step.sleepUntil(name: string, timestamp: Date | number): Promise<void> name - the name of the step. timestamp - a JavaScript Date object or milliseconds from the Unix epoch to sleep the Workflow instance until. step.waitForEvent(name: string, options: ): Promise<void> - name - the name of the step. - options - an object with properties for type (up to 100 characters 1 ), which determines which event type this waitForEvent call will match on when calling instance.sendEvent , and an optional timeout property, which defines how long the waitForEvent call will block for before throwing a timeout exception.

The default timeout is 24 hours. export class MyWorkflow extends WorkflowEntrypoint { async run ( event , step ) { // Other steps in your Workflow let stripeEvent = await step. waitForEvent ( "receive invoice paid webhook from Stripe" , { type: "stripe-webhook" , timeout: "1 hour" }, ); // Rest of your Workflow } } export class MyWorkflow extends WorkflowEntrypoint < Env , Params > { async run ( event : WorkflowEvent < Params >, step : WorkflowStep ) { // Other steps in your Workflow let stripeEvent = await step. waitForEvent < IncomingStripeWebhook >( "receive invoice paid webhook from Stripe" , { type: "stripe-webhook" , timeout: "1 hour" }, ); // Rest of your Workflow } } Review the documentation on events and parameters to learn how to send events to a running Workflow instance.

WorkflowStepConfig export type WorkflowDynamicDelayContext = { ctx : WorkflowStepContext ; error : Error ; }; export type WorkflowDelayFunction = ( input : WorkflowDynamicDelayContext , ) => string | number | Promise < string | number >; export type WorkflowStepConfig = { retries ?: { limit : number ; delay : string | number | WorkflowDelayFunction ; backoff ?: WorkflowBackoff ; }; timeout ?: string | number ; }; A WorkflowStepConfig is an optional argument to the do method of a WorkflowStep and defines properties that allow you to configure the retry behaviour of that step.

Set retries.delay to a fixed duration, or pass a WorkflowDel

The rest of this page is on the live site.