Overview

Flow Control allows you to limit how many workflow steps are executed by delaying and queuing their delivery.

This feature helps to:

• Manage resource consumption
• Prevent violations of external API rate limits
• Ensure workflows run within defined system constraints

How Flow Control Works#

When defined limits are exceeded, Flow Control automatically queues and delays step executions instead of rejecting them. This guarantees that all steps are eventually processed while staying within configured thresholds.

To configure Flow Control, you define a flow control key, a unique identifier used to group related steps under the same rate and parallelism limits. The steps that has the same flow control key respect the same constraints.

There are two main parameters to configure:

• Rate and Period: Maximum number of steps that may start within a time window
• Parallelism: Maximum number of steps allowed to run concurrently

These parameters can be combined for fine‑grained control. For example, you can allow up to 10 steps per minute but restrict concurrency to 5 steps in parallel, ensuring more predictable load patterns.

Example#

Suppose you have the following workflow:

export const { POST } = serve<{ topic: string }>(async (context) => {  const payload = context.requestPayload  await context.run("step-1", () => { ... });  await context.run("step-2", () => { ... });  await context.run("step-3", () => { ... });})

Now imagine you trigger N workflow runs for this workflow with the following configuration:

const { workflowRunId } = await client.trigger({  url: "https://<YOUR_WORKFLOW_ENDPOINT>/<YOUR-WORKFLOW-ROUTE>",  flowControl: {    key: "fw_example",    parallelism: 7,    rate: 3,    period: "1m",  }})

Without Flow Control, all workflow runs immediately execute their steps as soon as possible. If the workflow calls an external API in a step, this would likely result in ~N concurrent requests being fired in a very short timeframe, potentially overloading services or breaching API limits.

With the configuration above:

• Rate: At most 3 steps per minute can start across all workflow runs.
• Parallelism: At most 7 steps can be running at the same time.

Steps that exceed these limits are automatically queued and executed later.

Note that each step above corresponds to a separate workflow run. Because this workflow is sequential, each workflow run has only one pending step at a time. In workflows with parallel branches, multiple steps from the same workflow run may appear in the schedule simultaneously.

Parallelism slots are consumed by running steps. If no slots are available, new steps enter the waitlist until resources free up:

Step-level Flow Control#

The flow control configuration of a run applies to all of its steps. To limit a single context.run step more strictly, pass a flow control configuration as the third argument of context.run:

export const { POST } = serve(async (context) => {  await context.run("prepare", () => { ... });  await context.run(    "charge customer",    () => chargeCustomer(),    {      flowControl: { key: "payment-provider", parallelism: 3 },    }  );  await context.run("notify", () => { ... });});

Only the charge customer step is bound by the payment-provider key. The other steps keep the configuration the run was triggered with. Since the key is shared, at most 3 charge customer steps run at the same time across all runs using that key, no matter how many runs are active.

Following the analogy above, this lets you enforce a parallelism limit on the “green” steps only.

The step-level configuration replaces the run’s flow control for that step as a whole: a step with its own flow control configuration does not also count against the run’s flow control key.

context.call and context.invoke accept their own flow control configuration too:

• context.call – lets you run external HTTP requests under a separate key, so you can throttle third‑party API calls independently of your workflow logic.
• context.invoke – starts a new workflow run with its own flow control configuration.

Inside a step, context.flowControl returns the flow control configuration applied to the current delivery.

Configuration#

You can configure flow control when starting a workflow run:

import { Client } from "@upstash/workflow";const client = new Client({ token: "<QSTASH_TOKEN>" })const { workflowRunId } = await client.trigger({  url: "https://<YOUR_WORKFLOW_ENDPOINT>/<YOUR-WORKFLOW-ROUTE>",  flowControl: {    key: "user-signup",    parallelism: 1,    rate: 10,    period: 100,  }})

All steps within a workflow run will adhere to the specified flow control configuration.