> ## 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.

# API Examples

### Use QStash via:

* cURL
* [Typescript SDK](https://github.com/upstash/sdk-qstash-ts)
* [Python SDK](https://github.com/upstash/qstash-python)

Below are some examples to get you started. You can also check the [how to](/qstash/howto/publishing) section for more technical details.

### Publish a message to an endpoint

Simple example to [publish](/qstash/howto/publishing) a message to an endpoint.

<Tabs>
  <Tab title="cURL">
    ```shell theme={"system"}
    curl -XPOST \
        -H 'Authorization: Bearer XXX' \
        -H "Content-type: application/json" \
        -d '{ "hello": "world" }' \
        'https://qstash.upstash.io/v2/publish/https://example.com'
    ```
  </Tab>

  <Tab title="Typescript SDK">
    ```typescript theme={"system"}
    const client = new Client({ token: "<QSTASH_TOKEN>" });
    await client.publishJSON({
      url: "https://example.com",
      body: {
        hello: "world",
      },
    });
    ```
  </Tab>

  <Tab title="Python SDK">
    ```python theme={"system"}
    from qstash import QStash

    client = QStash("<QSTASH_TOKEN>")
    client.message.publish_json(
        url="https://example.com",
        body={
            "hello": "world",
        },
    )
    # Async version is also available
    ```
  </Tab>
</Tabs>

### Publish a message to a URL Group

The [URL Group](/qstash/features/url-groups) is a way to publish a message to multiple endpoints in a
fan out pattern.

<Tabs>
  <Tab title="cURL">
    ```shell theme={"system"}
    curl -XPOST \
        -H 'Authorization: Bearer XXX' \
        -H "Content-type: application/json" \
        -d '{ "hello": "world" }' \
        'https://qstash.upstash.io/v2/publish/myUrlGroup'
    ```
  </Tab>

  <Tab title="Typescript SDK">
    ```typescript theme={"system"}
    const client = new Client({ token: "<QSTASH_TOKEN>" });
    await client.publishJSON({
      urlGroup: "myUrlGroup",
      body: {
        hello: "world",
      },
    });
    ```
  </Tab>

  <Tab title="Python SDK">
    ```python theme={"system"}
    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
    ```
  </Tab>
</Tabs>

### 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.

<Tabs>
  <Tab title="cURL">
    ```shell theme={"system"}
    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'
    ```
  </Tab>

  <Tab title="Typescript SDK">
    ```typescript theme={"system"}
    const client = new Client({ token: "<QSTASH_TOKEN>" });
    await client.publishJSON({
      url: "https://example.com",
      body: {
        hello: "world",
      },
      delay: 300,
    });
    ```
  </Tab>

  <Tab title="Python SDK">
    ```python theme={"system"}
    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
    ```
  </Tab>
</Tabs>

### Send a custom header

Add a custom header to the message to be published.

<Tabs>
  <Tab title="cURL">
    ```shell theme={"system"}
    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'
    ```
  </Tab>

  <Tab title="Typescript SDK">
    ```typescript theme={"system"}
    const client = new Client({ token: "<QSTASH_TOKEN>" });
    await client.publishJSON({
      url: "https://example.com",
      body: {
        hello: "world",
      },
      headers: {
        "My-Header": "my-value",
      },
    });
    ```
  </Tab>

  <Tab title="Python SDK">
    ```python theme={"system"}
    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
    ```
  </Tab>
</Tabs>

### Schedule to run once a day

<Tabs>
  <Tab title="cURL">
    ```shell theme={"system"}
    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'
    ```
  </Tab>

  <Tab title="Typescript SDK">
    ```typescript theme={"system"}
    const client = new Client({ token: "<QSTASH_TOKEN>" });
    await client.schedules.create({
      destination: "https://example.com",
      cron: "0 0 * * *",
    });
    ```
  </Tab>

  <Tab title="Python SDK">
    ```python theme={"system"}
    from qstash import QStash

    client = QStash("<QSTASH_TOKEN>")
    client.schedule.create(
        destination="https://example.com",
        cron="0 0 * * *",
    )
    # Async version is also available
    ```
  </Tab>
</Tabs>

### Publish messages to a FIFO queue

By default, messges are published concurrently. With a [queue](/qstash/features/queues), you can enqueue messages in FIFO order.

<Tabs>
  <Tab title="cURL">
    ```shell theme={"system"}
    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!"}'
    ```
  </Tab>

  <Tab title="Typescript SDK">
    ```typescript theme={"system"}
    const client = new Client({ token: "<QSTASH_TOKEN>" });

    const queue = client.queue({
      queueName: "my-queue"
    })

    await queue.enqueueJSON({
      url: "https://example.com",
      body: {
        "Hello": "World"
      }
    })
    ```
  </Tab>

  <Tab title="Python SDK">
    ```python theme={"system"}
    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
    ```
  </Tab>
</Tabs>

### Publish messages in a [batch](/qstash/features/batch)

Publish multiple messages in a single request.

<Tabs>
  <Tab title="cURL">
    ```shell theme={"system"}
    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"
          }
         ]'
    ```
  </Tab>

  <Tab title="Typescript SDK">
    ```typescript theme={"system"}
    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",
      },
    ]);
    ```
  </Tab>

  <Tab title="Python SDK">
    ```python theme={"system"}
    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
    ```
  </Tab>
</Tabs>

### 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](/qstash/features/dlq).

<Tabs>
  <Tab title="cURL">
    ```shell theme={"system"}
    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'
    ```
  </Tab>

  <Tab title="Typescript SDK">
    ```typescript theme={"system"}
    const client = new Client({ token: "<QSTASH_TOKEN>" });
    await client.publishJSON({
      url: "https://example.com",
      body: {
        hello: "world",
      },
      retries: 3,
    });
    ```
  </Tab>

  <Tab title="Python SDK">
    ```python theme={"system"}
    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
    ```
  </Tab>
</Tabs>

### Set custom retry delay

Configure the delay between retry attempts when message delivery fails. [By default, QStash uses exponential backoff](/qstash/features/retry). You can customize this using mathematical expressions with the special variable `retried` (current retry attempt count starting from 0).

<Tabs>
  <Tab title="cURL">
    ```shell theme={"system"}
    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'
    ```
  </Tab>

  <Tab title="Typescript SDK">
    ```typescript theme={"system"}
    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
    });
    ```
  </Tab>

  <Tab title="Python SDK">
    ```python theme={"system"}
    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
    ```
  </Tab>
</Tabs>

**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.

<Tabs>
  <Tab title="cURL">
    ```shell theme={"system"}
    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'
    ```
  </Tab>

  <Tab title="Typescript SDK">
    ```typescript theme={"system"}
    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",
    });
    ```
  </Tab>

  <Tab title="Python SDK">
    ```python theme={"system"}
    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
    ```
  </Tab>
</Tabs>

### Get message logs

Retrieve logs for all messages that have been published (filtering is also available).

<Tabs>
  <Tab title="cURL">
    ```shell theme={"system"}
    curl https://qstash.upstash.io/v2/logs \
        -H "Authorization: Bearer XXX"
    ```
  </Tab>

  <Tab title="Typescript SDK">
    ```typescript theme={"system"}
    const client = new Client({ token: "<QSTASH_TOKEN>" });
    const logs = await client.logs()
    ```
  </Tab>

  <Tab title="Python SDK">
    ```python theme={"system"}
    from qstash import QStash

    client = QStash("<QSTASH_TOKEN>")
    client.event.list()
    # Async version is also available
    ```
  </Tab>
</Tabs>

### List all schedules

<Tabs>
  <Tab title="cURL">
    ```shell theme={"system"}
    curl https://qstash.upstash.io/v2/schedules \
        -H "Authorization: Bearer XXX"
    ```
  </Tab>

  <Tab title="Typescript SDK">
    ```typescript theme={"system"}
    const client = new Client({ token: "<QSTASH_TOKEN>" });
    const scheds = await client.schedules.list();
    ```
  </Tab>

  <Tab title="Python SDK">
    ```python theme={"system"}
    from qstash import QStash

    client = QStash("<QSTASH_TOKEN>")
    client.schedule.list()
    # Async version is also available
    ```
  </Tab>
</Tabs>