API Examples - Upstash Documentation

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 -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 QStashclient = 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 -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 QStashclient = 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 -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 QStashclient = QStash("<QSTASH_TOKEN>")client.message.publish_json(    url="https://example.com",    body={        "hello": "world",    },    delay="5m",)# Async version is also available

Send a custom header#

Add a custom header to the message to be published.

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 QStashclient = 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 -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 QStashclient = 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 -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 QStashclient = 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 -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 QStashclient = 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 -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 QStashclient = 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 -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 QStashclient = 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

Supported functions for retry delay expressions:

pow - Power function
sqrt - Square root
abs - Absolute value
exp - Exponential
floor - Floor function
ceil - Ceiling function
round - Rounding function
min - Minimum of values
max - Maximum of values

Examples:

1000 - Fixed 1 second delay
1000 * (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 -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 QStashclient = 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 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 QStashclient = QStash("<QSTASH_TOKEN>")client.event.list()# Async version is also available

List all schedules#

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 QStashclient = QStash("<QSTASH_TOKEN>")client.schedule.list()# Async version is also available