Workflow Client

Workflow client allows you to interact with your workflow runs. Currently, it has three basic functionality:

• cancel a running workflow run
• notify a workflow run waiting for an event
• get workflow runs waiting for some event

We are planning to add more functionality in the future. See the roadmap for more details.

​

Trigger Workflow

Using the trigger method, you can start a workflow run and get its run id.

import { Client } from "@upstash/workflow";

const client = new Client({ token: "<QSTASH_TOKEN>" })
const { workflowRunId } = await client.trigger({
  url: "https://workflow-endpoint.com",
  body: "hello there!",         // optional body
  headers: { ... },             // optional headers
  workflowRunId: "my-workflow", // optional workflow run id
  retries: 3                    // optional retries in the initial request
})

console.log(workflowRunId)
// prints wfr_my-workflow

If workflowRunId parameter isn’t passed, a run id will be generated randomly. If workflowRunId is passed, wfr_ prefix will be added to it.

For other alternatives of starting a workflow, see the documentation on starting a workflow run.

​

Cancel Workflow Runs

There are multiple ways you can cancel workflow runs:

• pass one or more workflow run ids to cancel them
• pass a workflow url to cancel all runs starting with this url
• cancel all pending or active workflow runs

​

Cancel a set of workflow runs

// cancel a single workflow
await client.cancel({ ids: "<WORKFLOW_RUN_ID>" })

// cancel a set of workflow runs
await client.cancel({ ids: [
  "<WORKFLOW_RUN_ID_1>",
  "<WORKFLOW_RUN_ID_2>",
]})

​

Cancel workflows starting with a url

If you have an endpoint called https://your-endpoint.com and you want to cancel all workflow runs on it, you can use urlStartingWith.

Note that this will cancel workflows in all endpoints under https://your-endpoint.com.

await client.cancel({ urlStartingWith: "https://your-endpoint.com" })

​

Cancel all workflows

To cancel all pending and currently running workflows, you can do it like this:

await client.cancel({ all: true })

​

Notify Waiting Workflow

To notify a workflow waiting for an event, you can use the notify method:

import { Client } from "@upstash/workflow";

const client = new Client({ token: "<QSTASH_TOKEN>" })
await client.notify({
  eventId: "my-event-id",
  eventData: "my-data" // data passed to the workflow run
});

The data passed in eventData will be available to the workflow run in the eventData field of the context.waitForEvent method.

​

Get Waiters of Event

To get the list of waiters for some event id, you can use the getWaiters method:

import { Client } from "@upstash/workflow";

const client = new Client({ token: "<QSTASH_TOKEN>" })
const result = await client.getWaiters({
  eventId: "my-event-id"
})

Result will be a list of Waiter objects: