Trigger Workflows

You can trigger Workflows both programmatically and via the Workflows APIs, including:

With Workers via HTTP requests in a fetch handler, or bindings from a queue or scheduled handler
Using the Workflows REST API
Via the wrangler CLI in your terminal

Workers API (Bindings)

You can interact with Workflows programmatically from any Worker script by creating a binding to a Workflow. A Worker can bind to multiple Workflows, including Workflows defined in other Workers projects (scripts) within your account.

You can interact with a Workflow:

Directly over HTTP via the fetch handler
From a Queue consumer inside a queue handler
From a Cron Trigger inside a scheduled handler
Within a Durable Object

To bind to a Workflow from your Workers code, you need to define a binding to a specific Workflow. For example, to bind to the Workflow defined in the get started guide, you would configure a wrangler.toml with the below:

wrangler.toml
wrangler.json

name = "workflows-tutorial"
main = "src/index.ts"
compatibility_date = "2024-10-22"

[[workflows]]
# The name of the Workflow
name = "workflows-tutorial"
# The binding name, which must be a valid JavaScript variable name.  This will
# be how you call (run) your Workflow from your other Workers handlers or
# scripts.
binding = "MY_WORKFLOW"
# Must match the class defined in your code that extends the Workflow class
class_name = "MyWorkflow"

{
  "name": "workflows-tutorial",
  "main": "src/index.ts",
  "compatibility_date": "2024-10-22",
  "workflows": [
    {
      "name": "workflows-tutorial",
      "binding": "MY_WORKFLOW",
      "class_name": "MyWorkflow"
    }
  ]
}

The binding = "MY_WORKFLOW" line defines the JavaScript variable that our Workflow methods are accessible on, including create (which triggers a new instance) or get (which returns the status of an existing instance).

The following example shows how you can manage Workflows from within a Worker, including:

Retrieving the status of an existing Workflow instance by its ID
Creating (triggering) a new Workflow instance
Returning the status of a given instance ID

interface Env {
  MY_WORKFLOW: Workflow;
}

export default {
  async fetch(req: Request, env: Env) {
    // Get instanceId from query parameters
    const instanceId = new URL(req.url).searchParams.get("instanceId")

    // If an ?instanceId=<id> query parameter is provided, fetch the status
    // of an existing Workflow by its ID.
    if (instanceId) {
      let instance = await env.MY_WORKFLOW.get(instanceId);
      return Response.json({
        status: await instance.status(),
      });
    }

    // Else, create a new instance of our Workflow, passing in any (optional)
    // params and return the ID.
    const newId = await crypto.randomUUID();
    let instance = await env.MY_WORKFLOW.create({ id: newId });
    return Response.json({
      id: instance.id,
      details: await instance.status(),
    });

    return Response.json({ result });
  },
};

Inspect a Workflow's status

You can inspect the status of any running Workflow instance by calling status against a specific instance ID. This allows you to programmatically inspect whether an instance is queued (waiting to be scheduled), actively running, paused, or errored.

let instance = await env.MY_WORKFLOW.get("abc-123")
let status = await instance.status() // Returns an InstanceStatus

The possible values of status are as follows:

  status:
    | "queued" // means that instance is waiting to be started (see concurrency limits)
    | "running"
    | "paused"
    | "errored"
    | "terminated" // user terminated the instance while it was running
    | "complete"
    | "waiting" // instance is hibernating and waiting for sleep or event to finish
    | "waitingForPause" // instance is finishing the current work to pause
    | "unknown";
  error?: string;
  output?: object;
};

Stop a Workflow

You can stop a Workflow instance by calling abort against a specific instance ID.

let instance = await env.MY_WORKFLOW.get("abc-123")
await instance.abort() // Returns Promise<void>

Once stopped, the Workflow instance cannot be resumed.

Restart a Workflow

let instance = await env.MY_WORKFLOW.get("abc-123")
await instance.restart() // Returns Promise<void>

Restarting an instance will immediately cancel any in-progress steps, erase any intermediate state, and treat the Workflow as if it was run for the first time.

REST API (HTTP)

Refer to the Workflows REST API documentation.

Command line (CLI)

Refer to the CLI quick start to learn more about how to manage and trigger Workflows via the command-line.

Was this helpful?

Cloudflare Dashboard Discord Community Learning Center Support Portal

Cookie Settings