List Failed Workflow Runs

List and paginate through all failed workflow runs currently in the DLQ.

Failed workflows end up in the DLQ after exhausting all retry attempts. You can filter,
paginate, and inspect these failures to understand what went wrong and decide whether to
resume, restart, or delete them.

1 min read

get/v2/workflows/dlq

Request example

curl --request GET \
  --url https://qstash-eu-central-1.upstash.io/v2/workflows/dlq?cursor=%3Cstring%3E&count=100&fromDate=1&toDate=1&workflowUrl=%3Cstring%3E&workflowRunId=%3Cstring%3E&workflowCreatedAt=1&label=%3Cstring%3E&failureFunctionState=%3Cstring%3E&callerIp=%3Cstring%3E&flowControlKey=%3Cstring%3E \
  --header 'Authorization: Bearer <token>'

Response

{
  "cursor": "<string>",
  "messages": [
    {
      "dlqId": "<string>",
      "workflowUrl": "<string>",
      "workflowRunId": "<string>",
      "workflowCreatedAt": 1,
      "url": "<string>",
      "method": "<string>",
      "header": {},
      "body": "<string>",
      "bodyBase64": "<string>",
      "maxRetries": 1,
      "createdAt": 1,
      "failureCallback": "<string>",
      "callerIP": "<string>",
      "label": "<string>",
      "labels": [
        "<string>"
      ],
      "flowControlKey": "<string>",
      "failureFunctionState": "<string>",
      "responseStatus": 1,
      "responseHeader": {},
      "responseBody": "<string>",
      "responseBodyBase64": "<string>"
    }
  ]
}

get/v2/workflows/dlq

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

cursorstring#

Pagination cursor. If provided, returns the next page of results.

countinteger#

The maximum number of failed workflow runs to return per page.

Default: 100

Range: <= 100

fromDateinteger#

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

toDateinteger#

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

workflowUrlstring[]#

Filter by workflow URL. Supports multiple values.

workflowRunIdstring#

Filter by workflow run ID.

workflowCreatedAtinteger#

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

labelstring[]#

Filter by label assigned to the workflow run. Supports multiple values. You can pass multiple values to match workflow runs 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 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 by IP address of the publisher. Supports multiple values.

flowControlKeystring[]#

Filter by Flow Control Key. Supports multiple values.

Responses

application/json

List of failed workflow runs

cursorstring#

Pagination cursor for the next page. Empty if no more results.

messagesobject[]#

Array of failed workflow messages.

Show child attributes

dlqIdstring#

The DLQ ID of the failed workflow message.

workflowUrlstring#

The URL of the workflow.

workflowRunIdstring#

The ID of the workflow run.

workflowCreatedAtinteger#

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

urlstring#

The URL of the failed workflow step.

methodstring#

The HTTP method used for the workflow step.

headerobject#

The HTTP headers sent to the workflow step.

Show child attributes

{key}string[]#

bodystring#

The body of the message if it is composed of utf8 chars only, empty otherwise.

bodyBase64string#

The base64 encoded body if the body contains a non-utf8 char only, empty otherwise.

maxRetriesinteger#

The number of retries that should be attempted in case of delivery failure.

createdAtinteger#

The unix timestamp in milliseconds when the message was created.

failureCallbackstring#

The url where we send a callback to after the workflow fails.

callerIPstring#

IP address of the publisher of this workflow.

labelstringdeprecated#

The label assigned to the workflow run. Deprecated in favor of labels.

labelsstring[]#

The list of labels assigned to the workflow run.

flowControlKeystring#

The flow control key used for rate limiting.

failureFunctionStatestring#

The state of the failure function if applicable.

responseStatusinteger#

The HTTP status code received from the destination API.

responseHeaderobject#

The HTTP response headers received from the destination API.

Show child attributes

{key}string[]#

responseBodystring#

The body of the response if it is composed of utf8 chars only, empty otherwise.

responseBodyBase64string#

The base64 encoded body of the response if the body contains a non-utf8 char only, empty otherwise.

List Workflow Run Logs Bulk Delete Failed Workflow Runs