Create a Schedule - Upstash Documentation

POST/v2/schedules/{destination}

cURL

curl --request POST \
  --url https://qstash-{region}.upstash.io/v2/schedules/{destination} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '<string>'

200Response

{
  "scheduleId": "<string>"
}

Authorization

Authorizationheaderstringrequired

Bearer authentication header of the form Bearer <token>.

Path parameters

destinationpathstringrequired

Destination can either be a valid URL where the message gets sent to, or a URL Group name.

If the destination is a URL, make sure the URL is prefixed with a valid protocol (http:// or https://)
If the destination is a URL Group, a new message will be created for each endpoint in the group.

Header parameters

Upstash-Cronheaderstringrequired

Cron expression defining the schedule frequency. QStash republishes this message whenever the cron expression triggers.

Timezones are supported and can be specified with the cron expression.

The maximum schedule resolution is 1 minute.

Upstash-Schedule-Idheaderstring

Assign a custom schedule ID to the created schedule. This header allows you to set the schedule ID yourself instead of QStash assigning a random ID.

If a schedule with the provided ID exists, the settings of the existing schedule will be updated with the new settings.

Content-Typeheaderstring

Content-Type is the MIME type of the message.

We highly recommend sending a Content-Type header along, as this will help your destination API to understand the content of the message.

Set this to whatever data you are sending through QStash, if your message is json, then use application/json. Some frameworks like Next.js will not parse your body correctly if the content type is not correct.

Examples:

application/json
application/xml
application/octet-stream
text/plain

Upstash-Methodheaderenum<string>default: "POST"

The HTTP method to use when sending the request to your API.

Available options:GETPOSTPUTPATCHDELETE

Upstash-Timeoutheaderstring

Specifies the maximum duration the request is allowed to take before timing out.

This parameter can be used to shorten the default allowed timeout value on your plan. See Max HTTP Connection Timeout on the pricing page for default values.

The format of this header is <value><unit> where value is a number and unit is one of:

s for seconds
m for minutes
h for hours.

Upstash-Retriesheaderinteger

How many times should this message be retried in case the destination API returns an error or is not available. The total number of deliveries is 1 (initial attempt) + retries.

If it is not provided, the default of 3 retries is used.

Upstash-Retry-Delayheaderstring

Customize the delay between retry attempts when message delivery fails.

By default, QStash uses exponential backoff. You can override this by providing a mathematical expressions to compute next delay. This expression is computed after each failed attempt.

You can use the special variable retried, which is current retry attempt. The retried is 0 for the first retry. This variable is provided during computation of the expression by QStash.

Supported functions:

Function	Description
`pow(x, y)`	Returns x raised to the power of y
`exp(x)`	Returns e raised to the power of x
`sqrt(x)`	Takes the square root of x
`abs(x)`	Returns the absolute value of x
`floor(x)`	Returns the largest integer less than or equal to x
`ceil(x)`	Returns the smallest integer greater than or equal to x
`round(x)`	Rounds x to the nearest integer
`min(x, y)`	Returns the smaller of x and y
`max(x, y)`	Returns the larger of x and y

Examples:

1000: Fixed 1 second delay
1000 * (1 + retried): Linear backoff
pow(2, retried) * 1000: Exponential backoff
max(1000, pow(2, retried) * 100): Exponential with minimum 1s delay

Upstash-Delayheaderstring

Delay the message delivery.

The format of this header is <value><unit> where value is a number and unit is one of:

s for seconds
m for minutes
h for hours.
d for days.

Upstash-Forward-*headerstring

You can send custom headers to your endpoint along with your message.

To send a custom header, prefix the header name with Upstash-Forward-. We will strip prefix and send them to the destination.

Header	Forwarded As
Upstash-Forward-My-Header: my-value	My-Header: my-value
Upstash-Forward-Authorization: Bearer	Authorization: Bearer

Upstash-Callbackheaderstring

You can define a callback url that will be called after each attempt. See the content of what will be delivered to a callback here The callback URL must be prefixed with a valid protocol (http:// or https://)

Callbacks are charged as a regular message. Callbacks will use the retry setting from the original request.

Upstash-Callback-Forward-*headerstring

You can send custom headers along with your callback message. To send a custom header, prefix the header name with Upstash-Callback-Forward-. We will strip prefix and them to the callback URL.

Example:

Upstash-Callback-Forward-My-Header: my-value will be forwarded as My-Header: my-value to your callback destination.

Upstash-Callback-*headerstring

You can customize the callback message configuration.

Header	Description
Upstash-Callback-Method	HTTP method to use for the callback request. Default is POST.
Upstash-Callback-Timeout	Timeout for the callback request. Format is same as Upstash-Timeout header.
Upstash-Callback-Retries	Number of retries for the callback request. Default is same as original message retries.
Upstash-Callback-Retry-Delay	Retry delay for the callback request. Format is same as Upstash-Retry-Delay header.

Upstash-Failure-Callbackheaderstring

You can define a failure callback url that will be called when a delivery is failed. That is when all the defined retries are exhausted. See the content of what will be delivered to a failure callback here The failure callback url must be prefixed with a valid protocol (http:// or https://) Callbacks are charged as a regular message. Callbacks will use the retry setting from the original request.

Upstash-Failure-Callback-Forward-*headerstring

You can send custom headers along with your failure callback message. To send a custom header, prefix the header name with Upstash-Failure-Callback-Forward-. We will strip prefix and them to the failure callback URL.

Example:

Upstash-Failure-Callback-Forward-My-Header: my-value will be forwarded as My-Header: my-value to your failure callback destination.

Upstash-Failure-Callback-*headerstring

You can customize the failure callback message configuration.

Header	Description
Upstash-Failure-Callback-Method	HTTP method to use for the callback request. Default is POST.
Upstash-Failure-Callback-Timeout	Timeout for the callback request. Format is same as Upstash-Timeout header.
Upstash-Failure-Callback-Retries	Number of retries for the callback request. Default is same as original message retries.
Upstash-Failure-Callback-Retry-Delay	Retry delay for the callback request. Format is same as Upstash-Retry-Delay header.

Upstash-Redact-Fieldsheaderstring

Comma-separated list of fields to redact from the message. Redacted fields appear as REDACTED:<SHA256> in the dashboard and API responses. The original values are still used when delivering messages to your endpoint.

Available options:

Option	Description
`body`	Redact the body of the message
`headers`	Redact all headers of the message
`header[header_name]`	Redact a specific header (e.g., `header[Authorization]`)

Examples:

body: Redact only the body
body, header[Authorization]: Redact the body and the Authorization header
body, headers: Redact both body and all headers

Upstash-Labelheaderstring

Label(s) to assign to the scheduled message for easier identification and filtering in logs and DLQ.

You can assign multiple labels by providing a comma-separated list.

Example: label_1,label_2

Body

bodyobjectrequired

The raw request message passed to the endpoints as is

Response

200 — Schedule created successfully

scheduleIdstring

Unique identifier for the schedule

400 — Schedule ID is invalid. Schedule IDs can only contain alphanumeric characters, hyphens, periods, and underscores.

errorstringrequired

Error message

412 — Exceeded the maximum number of schedules allowed.

errorstringrequired

Error message