Workflows

Cloudflare Workflows enables you to build reliable, long-running workflows that can survive Worker restarts and failures. Use the API to create, manage, and monitor workflow executions.

Overview

Access the Workflows API:

import Cloudflare from 'cloudflare';

const client = new Cloudflare({
  apiToken: process.env.CLOUDFLARE_API_TOKEN,
});

// Access Workflows resources
const workflows = client.workflows;

Manage workflow definitions.

Create or update a workflow

Create or modify a workflow definition.

const workflow = await client.workflows.update(
  'my-workflow',
  {
    account_id: '023e105f4ecef8ad9ca31a8372d0c353',
    class_name: 'MyWorkflow',
    script_name: 'my-worker',
  }
);

workflow_name

string

required

Name for the workflow

account_id

string

required

Your Cloudflare account ID

class_name

string

required

The exported Workflow class name from your Worker

script_name

string

required

The Worker script that contains the Workflow class

string

The workflow ID

name

string

The workflow name

class_name

string

The Workflow class name

script_name

string

The associated Worker script

created_on

string

ISO 8601 timestamp when the workflow was created

modified_on

string

ISO 8601 timestamp when the workflow was last modified

List workflows

Retrieve all workflows in your account.

for await (const workflow of client.workflows.list({
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
})) {
  console.log(workflow);
}

account_id

string

required

Your Cloudflare account ID

string

Filter workflows by name

page

number

Page number for pagination

per_page

number

Number of workflows per page (default: 20, max: 100)

instances

object

Instance count statistics

instances.queued

number

Number of queued instances

instances.running

number

Number of running instances

instances.complete

number

Number of completed instances

instances.errored

number

Number of errored instances

Get a workflow

Retrieve details about a specific workflow.

const workflow = await client.workflows.get(
  'my-workflow',
  { account_id: '023e105f4ecef8ad9ca31a8372d0c353' }
);

workflow_name

string

required

The workflow name

account_id

string

required

Your Cloudflare account ID

Delete a workflow

Delete a workflow definition.

await client.workflows.delete(
  'my-workflow',
  { account_id: '023e105f4ecef8ad9ca31a8372d0c353' }
);

workflow_name

string

required

The workflow name to delete

account_id

string

required

Your Cloudflare account ID

Instances

Manage workflow execution instances.

Create an instance

Start a new workflow instance.

const instance = await client.workflows.instances.create(
  'my-workflow',
  {
    account_id: '023e105f4ecef8ad9ca31a8372d0c353',
    params: { userId: '123', action: 'process' },
  }
);

workflow_name

string

required

The workflow name

account_id

string

required

Your Cloudflare account ID

params

object

Parameters to pass to the workflow instance

string

The instance ID

workflow_name

string

The workflow name

status

string

Instance status: ‘queued’, ‘running’, ‘complete’, ‘errored’, or ‘terminated’

created_on

string

ISO 8601 timestamp when the instance was created

List instances

Retrieve all instances for a workflow.

for await (const instance of client.workflows.instances.list(
  'my-workflow',
  { account_id: '023e105f4ecef8ad9ca31a8372d0c353' }
)) {
  console.log(instance);
}

workflow_name

string

required

The workflow name

account_id

string

required

Your Cloudflare account ID

status

string

Filter by status: ‘queued’, ‘running’, ‘complete’, ‘errored’, ‘paused’, ‘waiting’, ‘terminated’, or ‘waitingForPause’

page

number

Page number for pagination

per_page

number

Number of instances per page (default: 20, max: 100)

Get an instance

Retrieve details about a specific workflow instance.

const instance = await client.workflows.instances.get(
  'my-workflow',
  instanceId,
  { account_id: '023e105f4ecef8ad9ca31a8372d0c353' }
);

workflow_name

string

required

The workflow name

instance_id

string

required

The instance ID

account_id

string

required

Your Cloudflare account ID

string

The instance ID

status

string

Current instance status

output

object

The workflow output (if completed)

error

object

Error details (if errored)

Bulk instance operations

Terminate or pause multiple instances.

const result = await client.workflows.instances.bulk(
  'my-workflow',
  {
    account_id: '023e105f4ecef8ad9ca31a8372d0c353',
    action: 'terminate',
    instance_ids: [instanceId1, instanceId2],
  }
);

workflow_name

string

required

The workflow name

account_id

string

required

Your Cloudflare account ID

action

string

required

Action to perform: ‘terminate’ or ‘pause’

instance_ids

array

required

Array of instance IDs to act on

Versions

Track workflow version history.

List versions

Retrieve version history for a workflow.

for await (const version of client.workflows.versions.list(
  'my-workflow',
  { account_id: '023e105f4ecef8ad9ca31a8372d0c353' }
)) {
  console.log(version);
}

Get a version

Retrieve details about a specific workflow version.

const version = await client.workflows.versions.get(
  'my-workflow',
  versionId,
  { account_id: '023e105f4ecef8ad9ca31a8372d0c353' }
);

Defining workflows in Workers

Define a Workflow class in your Worker:

import { WorkflowEntrypoint, WorkflowStep } from 'cloudflare:workers';

export class MyWorkflow extends WorkflowEntrypoint {
  async run(event, step) {
    // Step 1: Fetch data
    const data = await step.do('fetch-data', async () => {
      const response = await fetch('https://api.example.com/data');
      return response.json();
    });
    
    // Step 2: Process data
    const result = await step.do('process-data', async () => {
      return processData(data);
    });
    
    // Step 3: Store result
    await step.do('store-result', async () => {
      await env.DB.prepare('INSERT INTO results VALUES (?)')
        .bind(JSON.stringify(result))
        .run();
    });
    
    return { success: true, result };
  }
}

export default {
  async fetch(request, env) {
    // Start a workflow instance
    const instance = await env.MY_WORKFLOW.create({
      params: { userId: '123' },
    });
    
    return Response.json({ instanceId: instance.id });
  },
};

Best practices

Idempotent steps: Each step should be idempotent to handle retries
Step naming: Use descriptive step names for easier debugging
Error handling: Use try-catch blocks within steps for granular error handling
State management: Store state in step results, not in memory
Timeouts: Be aware of step execution time limits
Monitoring: Regularly check instance status and error rates

Core Resources

Workers & Serverless

Application Services

Security & Access

Network Services

Developer Platform

Management & Monitoring

Workflows

Overview

Workflows

Create or update a workflow

List workflows

Get a workflow

Delete a workflow

Instances

Create an instance

List instances

Get an instance

Bulk instance operations

Versions

List versions

Get a version

Defining workflows in Workers

Best practices

Build docs developers (and LLMs) love

Core Resources

Workers & Serverless

Application Services

Security & Access

Network Services

Developer Platform

Management & Monitoring

​Overview

​Workflows

​Create or update a workflow

​List workflows

​Get a workflow

​Delete a workflow

​Instances

​Create an instance

​List instances

​Get an instance

​Bulk instance operations

​Versions

​List versions

​Get a version

​Defining workflows in Workers

​Best practices

Build docs developers (and LLMs) love

Overview

Workflows

Create or update a workflow

List workflows

Get a workflow

Delete a workflow

Instances

Create an instance

List instances

Get an instance

Bulk instance operations

Versions

List versions

Get a version

Defining workflows in Workers

Best practices