Bulk Restart Workflows from DLQ

Restart multiple failed workflow runs from the DLQ. Each workflow will start from the beginning.

Unlike resume, which continues from where workflows failed, restart executes the entire workflows
from the first step. New workflow run IDs are generated and all steps will be executed again.

A maximum of 50 workflow runs can be restarted per request. If more runs are available, a cursor is returned, which can be used in subsequent requests to continue the operation. When no cursor is returned, all entries have been processed.
Each restarted workflow run is assigned a new random Run ID.

1 min read

post/v2/workflows/dlq/restart

Request example

curl --request POST \
  --url https://qstash-eu-central-1.upstash.io/v2/workflows/dlq/restart \
  --header 'Authorization: Bearer <token>' \
  --header 'Upstash-Retries: 1' \
  --header 'Upstash-Delay: <string>' \
  --header 'Upstash-Retry-Delay: <string>' \
  --header 'Upstash-Flow-Control-Key: <string>' \
  --header 'Upstash-Flow-Control-Value: <string>' \
  --header 'Upstash-Label: <string>' \
  --header 'Upstash-Failure-Callback: <string>'

import requests

url = "https://qstash-eu-central-1.upstash.io/v2/workflows/dlq/restart"
headers = {
    "Authorization": "Bearer <token>",
    "Upstash-Retries": "1",
    "Upstash-Delay": "<string>",
    "Upstash-Retry-Delay": "<string>",
    "Upstash-Flow-Control-Key": "<string>",
    "Upstash-Flow-Control-Value": "<string>",
    "Upstash-Label": "<string>",
    "Upstash-Failure-Callback": "<string>",
}

response = requests.request("POST", url, headers=headers)

print(response.text)

const response = await fetch('https://qstash-eu-central-1.upstash.io/v2/workflows/dlq/restart', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <token>',
    'Upstash-Retries': '1',
    'Upstash-Delay': '<string>',
    'Upstash-Retry-Delay': '<string>',
    'Upstash-Flow-Control-Key': '<string>',
    'Upstash-Flow-Control-Value': '<string>',
    'Upstash-Label': '<string>',
    'Upstash-Failure-Callback': '<string>'
  }
});

const data = await response.json();
console.log(data);

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => 'https://qstash-eu-central-1.upstash.io/v2/workflows/dlq/restart',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer <token>',
    'Upstash-Retries: 1',
    'Upstash-Delay: <string>',
    'Upstash-Retry-Delay: <string>',
    'Upstash-Flow-Control-Key: <string>',
    'Upstash-Flow-Control-Value: <string>',
    'Upstash-Label: <string>',
    'Upstash-Failure-Callback: <string>',
  ],
]);

$response = curl_exec($curl);
curl_close($curl);

echo $response;

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://qstash-eu-central-1.upstash.io/v2/workflows/dlq/restart"

	req, _ := http.NewRequest("POST", url, nil)
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Upstash-Retries", "1")
	req.Header.Add("Upstash-Delay", "<string>")
	req.Header.Add("Upstash-Retry-Delay", "<string>")
	req.Header.Add("Upstash-Flow-Control-Key", "<string>")
	req.Header.Add("Upstash-Flow-Control-Value", "<string>")
	req.Header.Add("Upstash-Label", "<string>")
	req.Header.Add("Upstash-Failure-Callback", "<string>")

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))
}

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://qstash-eu-central-1.upstash.io/v2/workflows/dlq/restart"))
    .header("Authorization", "Bearer <token>")
    .header("Upstash-Retries", "1")
    .header("Upstash-Delay", "<string>")
    .header("Upstash-Retry-Delay", "<string>")
    .header("Upstash-Flow-Control-Key", "<string>")
    .header("Upstash-Flow-Control-Value", "<string>")
    .header("Upstash-Label", "<string>")
    .header("Upstash-Failure-Callback", "<string>")
    .method("POST", HttpRequest.BodyPublishers.noBody())
    .build();

HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());

require 'uri'
require 'net/http'

url = URI('https://qstash-eu-central-1.upstash.io/v2/workflows/dlq/restart')

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = url.scheme == 'https'

request = Net::HTTP::Post.new(url)
request['Authorization'] = 'Bearer <token>'
request['Upstash-Retries'] = '1'
request['Upstash-Delay'] = '<string>'
request['Upstash-Retry-Delay'] = '<string>'
request['Upstash-Flow-Control-Key'] = '<string>'
request['Upstash-Flow-Control-Value'] = '<string>'
request['Upstash-Label'] = '<string>'
request['Upstash-Failure-Callback'] = '<string>'

response = http.request(request)
puts response.read_body

Response

{
  "workflowRuns": [
    {
      "workflowRunId": "<string>",
      "workflowCreatedAt": 1
    }
  ],
  "cursor": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

post/v2/workflows/dlq/restart

Info

For multi-value filters, a workflow run matches if its value equals any of the given values (OR logic), and multiple filters are combined with AND logic.

Multiple values can be passed either by repeating the query parameter (label=label_1&label=label_2) or as a single comma-separated value (label=label_1,label_2).

Authorization

Authorizationstringheaderrequired#

QStash authentication token

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

Query parameters

dlqIdsstring[]#

List of specific DLQ IDs to restart. If provided, other filters are ignored.

cursorstring#

Pagination cursor for restarting workflows in batches.

countinteger#

Maximum number of workflows to restart. If not provided, all matching workflows will be restarted.

fromDateinteger#

Filter workflows by starting date, in milliseconds (Unix timestamp). This is inclusive.

toDateinteger#

Filter workflows by ending date, in milliseconds (Unix timestamp). This is inclusive.

workflowUrlstring[]#

Filter workflows by workflow URL. Supports multiple values.

workflowRunIdstring#

Filter workflows by workflow run ID.

workflowCreatedAtinteger#

Filter workflows by creation timestamp in milliseconds (Unix timestamp).

labelstring[]#

Filter workflows by label. Supports multiple values. You can pass multiple values to match workflows with any of the given labels (OR logic).

Examples:

label=my_label
label=label_1&label=label_2
label=label_1,label_2

failureFunctionStatestring[]#

Filter workflows by failure function state. Supports multiple values.

State	Description
CALLBACK_INPROGRESS	The failure function is in progress.
CALLBACK_SUCCESS	The failure function run successfully.
CALLBACK_FAIL	The failure function failed to run.
CALLBACK_CANCELED	The failure function was manually canceled

callerIpstring[]#

Filter workflows by IP address of the publisher. Supports multiple values.

flowControlKeystring[]#

Filter workflows by Flow Control Key. Supports multiple values.

Headers

Upstash-Retriesinteger#

Override the number of retries for the workflow steps.

Upstash-Delaystring#

Override the delay before executing the workflows. Format is <value><unit> (e.g., "10s", "5m").

Upstash-Retry-Delaystring#

Override the retry delay expression for the workflow steps.

Upstash-Flow-Control-Keystring#

Override the flow control key for the workflows.

Upstash-Flow-Control-Valuestring#

Override the flow control configuration in the format parallelism=<value>, rate=<value>, period=<value>.

Upstash-Labelstring#

Override the label(s) for the workflows.

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

Example: label_1,label_2

Upstash-Failure-Callbackstring#

Override the failure callback URL for the workflows.

Responses

application/json

Workflows restarted successfully

workflowRunsobject[]#

Array of restarted workflow runs.

Show child attributes

workflowRunIdstring#

The ID of the restarted workflow run (a new ID is generated for each restarted run).

workflowCreatedAtinteger#

The timestamp when the restarted workflow run was created (Unix timestamp in milliseconds).

cursorstring#

Pagination cursor to use in subsequent requests. If empty, all matching workflows have been processed.

Restart Workflow from DLQ Retry Failure Callback