Queues - Upstash Documentation

The queue concept in QStash allows ordered delivery (FIFO). See the API doc for the full list of related Rest APIs. Here we list common use cases for Queue and how to use them.

Ordered Delivery

With Queues, the ordered delivery is guaranteed by default. This means:

Your messages will be queued without blocking the REST API and sent one by one in FIFO order. Queued means CREATED event will be logged.
The next message will wait for retries of the current one if it can not be delivered because your endpoint returns non-2xx code. In other words, the next message will be ACTIVE only after the last message is either DELIVERED or FAILED.
Next message will wait for callbacks or failure callbacks to finish.

cURL

curl -XPOST -H 'Authorization: Bearer XXX' \            -H "Content-type: application/json" \  'https://qstash.upstash.io/v2/enqueue/my-queue/https://example.com' -d '{"message":"Hello, World!"}'

TypeScript

const client = new Client({ token: "<QSTASH_TOKEN>" });const queue = client.queue({  queueName: "my-queue"})await queue.enqueueJSON({  url: "https://example.com",  body: {    "Hello": "World"  }})

Python

from qstash import QStashclient = QStash("<QSTASH_TOKEN>")client.message.enqueue_json(    queue="my-queue",    url="https://example.com",    body={        "Hello": "World",    },)

Controlled Parallelism

For the parallelism limit, we introduced an easier and less limited API with publish. Please check the Flow Control page for the detailed information.

Setting parallelism with queues will be deprecated at some point.

To ensure that your endpoint is not overwhelmed and also you want more than one-by-one delivery for better throughput, you can achieve controlled parallelism with queues.

By default, queues have parallelism 1. Depending on your plan, you can configure the parallelism of your queues as follows:

cURL

curl -XPOST https://qstash.upstash.io/v2/queues/ \  -H "Authorization: Bearer <token>" \  -H "Content-Type: application/json" \  -d '{    "queueName": "my-queue",     "parallelism": 5,  }'

TypeScript

const client = new Client({ token: "<QSTASH_TOKEN>" });const queue = client.queue({  queueName: "my-queue"})await queue.upsert({  parallelism: 1,})

Python

from qstash import QStashclient = QStash("<QSTASH_TOKEN>")client.queue.upsert("my-queue", parallelism=5)

After that, you can use the enqueue path to send your messages.

cURL

curl -XPOST -H 'Authorization: Bearer XXX' \             -H "Content-type: application/json" \  'https://qstash.upstash.io/v2/enqueue/my-queue/https://example.com' -d '{"message":"Hello, World!"}'

TypeScript

const client = new Client({ token: "<QSTASH_TOKEN>" });const queue = QStashClient.queue({  queueName: "my-queue"})await queue.enqueueJSON({  url: "https://example.com",  body: {    "Hello": "World"  }})

Python

from qstash import QStashclient = QStash("<QSTASH_TOKEN>")client.message.enqueue_json(    queue="my-queue",    url="https://example.com",    body={        "Hello": "World",    },)

You can check the parallelism of your queues with the following API:

cURL

curl https://qstash.upstash.io/v2/queues/my-queue \  -H "Authorization: Bearer <token>"

TypeScript

const client = new Client({ token: "<QSTASH_TOKEN>" });const queue = client.queue({  queueName: "my-queue"})const res = await queue.get()

Python

from qstash import QStashclient = QStash("<QSTASH_TOKEN>")client.queue.get("my-queue")