Features
Batching
Publishing is great for sending one message at a time, but sometimes you want to send a batch of messages at once.
This can be useful to send messages to a single or multiple destinations.
QStash provides the batch endpoint to help
you with this.
If the format of the messages are valid, the response will be an array of responses for each message in the batch. When batching URL Groups, the response will be an array of responses for each destination in the URL Group. If one message fails to be sent, that message will have an error response, but the other messages will still be sent.
You can publish to destination, URL Group or queue in the same batch request.
Batching messages with destinations
You can also send messages to the same destination!
cURL
curl -XPOST https://qstash.upstash.io/v2/batch \ -H 'Authorization: Bearer XXX' \ -H "Content-type: application/json" \ -d ' [ { "destination": "https://example.com/destination1" }, { "destination": "https://example.com/destination2" } ]'TypeScript
import { Client } from "@upstash/qstash";// Each message is the same as the one you would send with the publish endpointconst client = new Client({ token: "<QSTASH_TOKEN>" });const res = await client.batchJSON([ { url: "https://example.com/destination1", }, { url: "https://example.com/destination2", },]);Python
from qstash import QStashclient = QStash("<QSTASH-TOKEN>")client.message.batch_json( [ {"url": "https://example.com/destination1"}, {"url": "https://example.com/destination2"}, ])Batching messages with URL Groups
If you have a URL Group, you can batch send with the URL Group as well.
cURL
curl -XPOST https://qstash.upstash.io/v2/batch \ -H 'Authorization: Bearer XXX' \ -H "Content-type: application/json" \ -d ' [ { "destination": "myUrlGroup" }, { "destination": "https://example.com/destination2" } ]'TypeScript
const client = new Client({ token: "<QSTASH_TOKEN>" });// Each message is the same as the one you would send with the publish endpointconst res = await client.batchJSON([ { urlGroup: "myUrlGroup", }, { url: "https://example.com/destination2", },]);Python
from qstash import QStashclient = QStash("<QSTASH-TOKEN>")client.message.batch_json( [ {"url_group": "my-url-group"}, {"url": "https://example.com/destination2"}, ])Batching messages with queue
If you have a queue, you can batch send with the queue. It is the same as publishing to a destination, but you need to set the queue name.
cURL
curl -XPOST https://qstash.upstash.io/v2/batch \ -H 'Authorization: Bearer XXX' \ -H "Content-type: application/json" \ -d ' [ { "queue": "my-queue", "destination": "https://example.com/destination1" }, { "queue": "my-second-queue", "destination": "https://example.com/destination2" } ]'TypeScript
const client = new Client({ token: "<QSTASH_TOKEN>" });const res = await client.batchJSON([ { queueName: "my-queue", url: "https://example.com/destination1", }, { queueName: "my-second-queue", url: "https://example.com/destination2", },]);Python
from upstash_qstash import QStashfrom upstash_qstash.message import BatchRequestqstash = QStash("<QSTASH_TOKEN>")messages = [ BatchRequest( queue="my-queue", url="https://httpstat.us/200", body=f"hi 1", retries=0 ), BatchRequest( queue="my-second-queue", url="https://httpstat.us/200", body=f"hi 2", retries=0 ),]qstash.message.batch(messages)Batching messages with headers and body
You can provide custom headers and a body for each message in the batch.
cURL
curl -XPOST https://qstash.upstash.io/v2/batch -H "Authorization: Bearer XXX" \ -H "Content-Type: application/json" \ -d ' [ { "destination": "myUrlGroup", "headers":{ "Upstash-Delay":"5s", "Upstash-Forward-Hello":"123456" }, "body": "Hello World" }, { "destination": "https://example.com/destination1", "headers":{ "Upstash-Delay":"7s", "Upstash-Forward-Hello":"789" } }, { "destination": "https://example.com/destination2", "headers":{ "Upstash-Delay":"9s", "Upstash-Forward-Hello":"again" } } ]'TypeScript
const client = new Client({ token: "<QSTASH_TOKEN>" });// Each message is the same as the one you would send with the publish endpointconst msgs = [ { urlGroup: "myUrlGroup", delay: 5, body: "Hello World", headers: { hello: "123456", }, }, { url: "https://example.com/destination1", delay: 7, headers: { hello: "789", }, }, { url: "https://example.com/destination2", delay: 9, headers: { hello: "again", }, body: { Some: "Data", }, },];const res = await client.batchJSON(msgs);Python
from qstash import QStashclient = QStash("<QSTASH-TOKEN>")client.message.batch_json( [ { "url_group": "my-url-group", "delay": "5s", "body": {"hello": "world"}, "headers": {"random": "header"}, }, { "url": "https://example.com/destination1", "delay": "1m", }, { "url": "https://example.com/destination2", "body": {"hello": "again"}, }, ])The response for this will look like
[ [ { "messageId": "msg_...", "url": "https://myUrlGroup-endpoint1.com" }, { "messageId": "msg_...", "url": "https://myUrlGroup-endpoint2.com" } ], { "messageId": "msg_..." }, { "messageId": "msg_..." }]