Workflows

Orchestrate long-running tasks with Cloudflare 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;

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

id · 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

search · 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

id · 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

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

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