Documentation Index
Fetch the complete documentation index at: https://upstash.com/docs/llms.txt
Use this file to discover all available pages before exploring further.
Use QStash via:
Below are some examples to get you started. You can also check the how to section for more technical details.
Publish a message to an endpoint
Simple example to publish a message to an endpoint.
cURL
Typescript SDK
Python SDK
curl -XPOST \
-H 'Authorization: Bearer XXX' \
-H "Content-type: application/json" \
-d '{ "hello": "world" }' \
'https://qstash.upstash.io/v2/publish/https://example.com'
const client = new Client({ token: "<QSTASH_TOKEN>" });
await client.publishJSON({
url: "https://example.com",
body: {
hello: "world",
},
});
from qstash import QStash
client = QStash("<QSTASH_TOKEN>")
client.message.publish_json(
url="https://example.com",
body={
"hello": "world",
},
)
# Async version is also available
Publish a message to a URL Group
The URL Group is a way to publish a message to multiple endpoints in a
fan out pattern.
cURL
Typescript SDK
Python SDK
curl -XPOST \
-H 'Authorization: Bearer XXX' \
-H "Content-type: application/json" \
-d '{ "hello": "world" }' \
'https://qstash.upstash.io/v2/publish/myUrlGroup'
const client = new Client({ token: "<QSTASH_TOKEN>" });
await client.publishJSON({
urlGroup: "myUrlGroup",
body: {
hello: "world",
},
});
from qstash import QStash
client = QStash("<QSTASH_TOKEN>")
client.message.publish_json(
url_group="my-url-group",
body={
"hello": "world",
},
)
# Async version is also available
Publish a message with 5 minutes delay
Add a delay to the message to be published. After QStash receives the message,
it will wait for the specified time (5 minutes in this example) before sending the message to the endpoint.
cURL
Typescript SDK
Python SDK
curl -XPOST \
-H 'Authorization: Bearer XXX' \
-H "Content-type: application/json" \
-H "Upstash-Delay: 5m" \
-d '{ "hello": "world" }' \
'https://qstash.upstash.io/v2/publish/https://example.com'
const client = new Client({ token: "<QSTASH_TOKEN>" });
await client.publishJSON({
url: "https://example.com",
body: {
hello: "world",
},
delay: 300,
});
from qstash import QStash
client = QStash("<QSTASH_TOKEN>")
client.message.publish_json(
url="https://example.com",
body={
"hello": "world",
},
delay="5m",
)
# Async version is also available
cURL
Typescript SDK
Python SDK
curl -XPOST \
-H 'Authorization: Bearer XXX' \
-H 'Upstash-Forward-My-Header: my-value' \
-H "Content-type: application/json" \
-d '{ "hello": "world" }' \
'https://qstash.upstash.io/v2/publish/https://example.com'
const client = new Client({ token: "<QSTASH_TOKEN>" });
await client.publishJSON({
url: "https://example.com",
body: {
hello: "world",
},
headers: {
"My-Header": "my-value",
},
});
from qstash import QStash
client = QStash("<QSTASH_TOKEN>")
client.message.publish_json(
url="https://example.com",
body={
"hello": "world",
},
headers={
"My-Header": "my-value",
},
)
# Async version is also available
Schedule to run once a day
cURL
Typescript SDK
Python SDK
curl -XPOST \
-H 'Authorization: Bearer XXX' \
-H "Upstash-Cron: 0 0 * * *" \
-H "Content-type: application/json" \
-d '{ "hello": "world" }' \
'https://qstash.upstash.io/v2/schedules/https://example.com'
const client = new Client({ token: "<QSTASH_TOKEN>" });
await client.schedules.create({
destination: "https://example.com",
cron: "0 0 * * *",
});
from qstash import QStash
client = QStash("<QSTASH_TOKEN>")
client.schedule.create(
destination="https://example.com",
cron="0 0 * * *",
)
# Async version is also available
Publish messages to a FIFO queue
By default, messges are published concurrently. With a queue, you can enqueue messages in FIFO order.
cURL
Typescript SDK
Python SDK
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!"}'
const client = new Client({ token: "<QSTASH_TOKEN>" });
const queue = client.queue({
queueName: "my-queue"
})
await queue.enqueueJSON({
url: "https://example.com",
body: {
"Hello": "World"
}
})
from qstash import QStash
client = QStash("<QSTASH_TOKEN>")
client.message.enqueue_json(
queue="my-queue",
url="https://example.com",
body={
"Hello": "World",
},
)
# Async version is also available
Publish messages in a batch
Publish multiple messages in a single request.
cURL
Typescript SDK
Python SDK
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"
}
]'
import { Client } from "@upstash/qstash";
const client = new Client({ token: "<QSTASH_TOKEN>" });
const res = await client.batchJSON([
{
url: "https://example.com/destination1",
},
{
url: "https://example.com/destination2",
},
]);
from qstash import QStash
client = QStash("<QSTASH_TOKEN>")
client.message.batch_json(
[
{
"url": "https://example.com/destination1",
},
{
"url": "https://example.com/destination2",
},
]
)
# Async version is also available
Set max retry count to 3
Configure how many times QStash should retry to send the message to the endpoint before
sending it to the dead letter queue.
cURL
Typescript SDK
Python SDK
curl -XPOST \
-H 'Authorization: Bearer XXX' \
-H "Upstash-Retries: 3" \
-H "Content-type: application/json" \
-d '{ "hello": "world" }' \
'https://qstash.upstash.io/v2/publish/https://example.com'
const client = new Client({ token: "<QSTASH_TOKEN>" });
await client.publishJSON({
url: "https://example.com",
body: {
hello: "world",
},
retries: 3,
});
from qstash import QStash
client = QStash("<QSTASH_TOKEN>")
client.message.publish_json(
url="https://example.com",
body={
"hello": "world",
},
retries=3,
)
# Async version is also available
Set custom retry delay
Configure the delay between retry attempts when message delivery fails. By default, QStash uses exponential backoff. You can customize this using mathematical expressions with the special variable retried (current retry attempt count starting from 0).
cURL
Typescript SDK
Python SDK
curl -XPOST \
-H 'Authorization: Bearer XXX' \
-H "Upstash-Retries: 3" \
-H "Upstash-Retry-Delay: pow(2, retried) * 1000" \
-H "Content-type: application/json" \
-d '{ "hello": "world" }' \
'https://qstash.upstash.io/v2/publish/https://example.com'
const client = new Client({ token: "<QSTASH_TOKEN>" });
await client.publishJSON({
url: "https://example.com",
body: {
hello: "world",
},
retries: 3,
retryDelay: "pow(2, retried) * 1000", // 2^retried * 1000ms
});
from qstash import QStash
client = QStash("<QSTASH_TOKEN>")
client.message.publish_json(
url="https://example.com",
body={
"hello": "world",
},
retries=3,
retry_delay="pow(2, retried) * 1000", # 2^retried * 1000ms
)
# Async version is also available
pow - Power functionsqrt - Square rootabs - Absolute valueexp - Exponentialfloor - Floor functionceil - Ceiling functionround - Rounding functionmin - Minimum of valuesmax - Maximum of values
Examples:
1000 - Fixed 1 second delay1000 * (1 + retried) - Linear backoff: 1s, 2s, 3s, 4s…pow(2, retried) * 1000 - Exponential backoff: 1s, 2s, 4s, 8s…max(1000, pow(2, retried) * 100) - Exponential with minimum 1s delay
Set callback url
Receive a response from the endpoint and send it to the specified callback URL.
If the endpoint does not return a response, QStash will send it to the failure callback URL.
cURL
Typescript SDK
Python SDK
curl -XPOST \
-H 'Authorization: Bearer XXX' \
-H "Content-type: application/json" \
-H "Upstash-Callback: https://example.com/callback" \
-H "Upstash-Failure-Callback: https://example.com/failure" \
-d '{ "hello": "world" }' \
'https://qstash.upstash.io/v2/publish/https://example.com'
const client = new Client({ token: "<QSTASH_TOKEN>" });
await client.publishJSON({
url: "https://example.com",
body: {
hello: "world",
},
callback: "https://example.com/callback",
failureCallback: "https://example.com/failure",
});
from qstash import QStash
client = QStash("<QSTASH_TOKEN>")
client.message.publish_json(
url="https://example.com",
body={
"hello": "world",
},
callback="https://example.com/callback",
failure_callback="https://example.com/failure",
)
# Async version is also available
Get message logs
Retrieve logs for all messages that have been published (filtering is also available).
cURL
Typescript SDK
Python SDK
curl https://qstash.upstash.io/v2/logs \
-H "Authorization: Bearer XXX"
const client = new Client({ token: "<QSTASH_TOKEN>" });
const logs = await client.logs()
from qstash import QStash
client = QStash("<QSTASH_TOKEN>")
client.event.list()
# Async version is also available
List all schedules
cURL
Typescript SDK
Python SDK
curl https://qstash.upstash.io/v2/schedules \
-H "Authorization: Bearer XXX"
const client = new Client({ token: "<QSTASH_TOKEN>" });
const scheds = await client.schedules.list();
from qstash import QStash
client = QStash("<QSTASH_TOKEN>")
client.schedule.list()
# Async version is also available
