Skip to main content

Delay

When publishing a message, you can delay it for a certain amount of time before it will be delivered to your API. The maximum delay is 90 days.

Relative Delay​

Delay a message by a certain amount of time relative to the time the message was published.

The format for the duration is <number><unit>. Here are some examples:

  • 10s = 10 seconds
  • 1m = 1 minute
  • 30m = half an hour
  • 2h = 2 hours
  • 7d = 7 days

You can send this duration inside the Upstash-Delay header.

curl -XPOST \
    -H 'Authorization: Bearer XXX' \
    -H "Content-type: application/json" \
    -H "Upstash-Delay: 1m" \
    -d '{ "hello": "world" }' \
    'https://qstash.upstash.io/v1/publish/...'
danger

Upstash-Delay will get overridden by Upstash-Not-Before header when both are used together.

Absolute Delay​

Delay a message until a certain time in the future. The format is a unix timestamp in seconds, based on the UTC timezone.

You can send the timestamp inside the Upstash-Not-Before header.

curl -XPOST \
    -H 'Authorization: Bearer XXX' \
    -H "Content-type: application/json" \
    -H "Upstash-Not-Before: 1657104947" \
    -d '{ "hello": "world" }' \
    'https://qstash.upstash.io/v1/publish/...'
info

Upstash-Not-Before will override the Upstash-Delay header when both are used together.

Delays in Schedules​

When adding a delay either via Upstash-Delay or Upstash-Not-Before, the delay will affect the messages that will be created by the schedule and not the schedule itself.

For example when you create a new schedule with a delay of 30s, the messages will be created when the schedule triggers but only delivered after 30 seconds.