Rate and Period

Control how many Upstash Workflow steps start within a time window using rate and period limits, queuing excess steps for the next window.

The rate specifies the maximum number of requests allowed in a given period (time window).

Configure Retry Attempt Count

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",
    rate: 10,
    period: 100,
  }
})

Example: If rate = 2 and period = 1 minute, then a maximum of 2 steps can be executed per minute.

The first 2 requests within the minute are executed immediately:

The 3rd request in the same minute is not executed immediately:

Instead of rejecting it, Workflow schedules the request in the next available time window:

Note that step executions may take longer than the defined period. The rate limit only controls how many steps are started within each time window, it does not limit their execution duration.