Trigger Workflow Run

Start a new workflow run.

1 min read

post/v2/trigger/{workflowUrl}

Request example

curl --request POST \
  --url https://qstash-eu-central-1.upstash.io/v2/trigger/%3Cstring%3E \
  --header 'Authorization: Bearer <token>' \
  --header 'Upstash-Workflow-RunId: <string>' \
  --header 'Upstash-Forward-*: <string>' \
  --header 'Upstash-Retries: 3' \
  --header 'Upstash-Delay: 50s' \
  --header 'Upstash-Not-Before: 1' \
  --header 'Upstash-Label: <string>' \
  --header 'Upstash-Flow-Control-Key: <string>' \
  --header 'Upstash-Flow-Control-Value: <string>' \
  --header 'Upstash-Failure-Callback: <string>' \
  --header 'Upstash-Failure-Callback-Forward-*: <string>' \
  --header 'Upstash-Retry-Delay: <string>' \
  --header 'Content-Type: application/json' \
  --data '{}'

Response

{
  "workflowRunId": "<string>",
  "workflowCreatedAt": 1
}

post/v2/trigger/{workflowUrl}

Authorization

Authorizationstringheaderrequired#

QStash authentication token

1 alternative authorization method available — see the spec for details.

Path parameters

workflowUrlstringrequired#

The URL of the workflow to trigger.

Headers

Upstash-Workflow-RunIdstring#

Optional custom run ID for the workflow run. A random ID will be generated if not provided.

Upstash-Forward-*string#

You can send custom headers to your workflow.

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

Header	Forwarded To Destination As
Upstash-Forward-My-Header: my-value	My-Header: my-value
Upstash-Forward-Authorization: Bearer <token>	Authorization: Bearer <token>

Upstash-Retriesinteger#

Number of retries for the workflow steps in case of failure.

Default: 3

Upstash-Delaystring#

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-Not-Beforeinteger#

Delay the message delivery until a certain timestamp in the future.

The format is a unix timestamp in seconds, based on the UTC timezone.

When both Upstash-Not-Before and Upstash-Delay headers are provided, Upstash-Not-Before will take precedence.

Upstash-Labelstring#

Optional label(s) to attach to the workflow run for easier identification in logs and DLQ.

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

Example: label_1,label_2

Upstash-Flow-Control-Keystring#

Flow control key to manage concurrency for the workflow run. Steps with the same key will respect the same concurrency limit.
Make sure you pass Upstash-Flow-Control-Value header as well to define the limits for the key.

Upstash-Flow-Control-Valuestring#

Parallelism and rate limit configuration for the flow control key in the format:
parallelism=<value>, rate=<value>, period=<value>.
See flow control for details.

Upstash-Failure-Callbackstring#

Failure callback URL to be called if the workflow run fails after all retries. That is when all the defined retries are exhausted. To call the failure function defined on server, this options should be left empty. A url should be given with this header only to call a different endpoint on failure. See failureUrl.

Failure callback URL must be prefixed with a valid protocol (http:// or https://)
Failure callbacks are charged as a regular message.
Failure callbacks will use the retry setting from the original request.

Upstash-Failure-Callback-Forward-*string#

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.

Header	Forwarded To Callback Destination As
Upstash-Failure-Callback-Forward-My-Header: my-value	My-Header: my-value
Upstash-Failure-Callback-Forward-Authorization: Bearer <token>	Authorization: Bearer <token>

Upstash-Retry-Delaystring#

Customize the delay between retry attempts when step delivery fails.

By default, Upstash Workflow 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 how many times the message has been retried. The retried is 0 for the first retry.

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

Body

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

bodyobject#

The raw request payload passed to the workflow endpoints as is. You can access it via requestPayload parameter on the context object.

Responses

application/json

Workflow triggered successfully

workflowRunIdstring#

The ID of the triggered workflow run.

workflowCreatedAtnumber#

The timestamp when the workflow run was created.

Examples Batch Trigger Workflow Runs