Flow Control

FlowControl enables you to limit the number of messages sent to your endpoint via delaying the delivery. There are two limits that you can set with the FlowControl feature: RatePerSecond and Parallelism. And if needed both parameters can be combined.

For the FlowControl, you need to choose a key first. This key is used to count the number of calls made to your endpoint.

There are not limits to number of keys you can use.

​

RatePerSecond Limit

The rate limit is the number of calls that can be made to your endpoint per second. QStash will delay the delivery of the messages if the rate limit is exceeded. In case of burst calls to QStash, a delivery can be delayed as long as necessary to guarantee the rate limit.

You can set the rate limit 10 calls per second as follows:

const client = new Client({ token: "<QSTASH_TOKEN>" });

await client.publishJSON({
    url: "https://example.com",
    body: { hello: "world" },
    flowControl: { key: "USER_GIVEN_KEY", ratePerSecond: 10 },
});

​

Parallelism Limit

The parallelism limit is the number of calls that can be active at the same time. Active means that the call is made to your endpoint and the response is not received yet.

You can set the parallelism limit to 10 calls active at the same time as follows:

const client = new Client({ token: "<QSTASH_TOKEN>" });

await client.publishJSON({
    url: "https://example.com",
    body: { hello: "world" },
    flowControl: { key: "USER_GIVEN_KEY", parallelism: 10 },
});

​

RatePerSecond and Parallelism Together

Both parameters can be combined. For example, with a rate of 20 per second and parallelism of 10, if each request takes a minute to complete, QStash will trigger 20 calls in the first second and another 20 in the next. Since none of them will have finished, the system will wait until one completes before triggering another.

const client = new Client({ token: "<QSTASH_TOKEN>" });

await client.publishJSON({
    url: "https://example.com",
    body: { hello: "world" },
    flowControl: { key: "USER_GIVEN_KEY", ratePerSecond: 20, parallelism: 10 },
});