Skip to main content
GET
/
v2
/
workflows
/
dlq
List Failed Workflow Runs
curl --request GET \
  --url https://qstash-{region}.upstash.io/v2/workflows/dlq \
  --header 'Authorization: Bearer <token>'
{
  "cursor": "<string>",
  "messages": [
    {
      "dlqId": "<string>",
      "workflowUrl": "<string>",
      "workflowRunId": "<string>",
      "workflowCreatedAt": 123,
      "url": "<string>",
      "method": "<string>",
      "header": {},
      "body": "<string>",
      "bodyBase64": "<string>",
      "maxRetries": 123,
      "createdAt": 123,
      "failureCallback": "<string>",
      "callerIP": "<string>",
      "label": "<string>",
      "labels": [
        "<string>"
      ],
      "flowControlKey": "<string>",
      "failureFunctionState": "<string>",
      "responseStatus": 123,
      "responseHeader": {},
      "responseBody": "<string>",
      "responseBodyBase64": "<string>"
    }
  ]
}
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).

Authorizations

​
Authorization
string
header
required

QStash authentication token

Query Parameters

​
cursor
string

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

​
count
integer
default:100

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

Required range: x <= 100
​
fromDate
integer<int64>

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

​
toDate
integer<int64>

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

​
workflowUrl
string[]

Filter by workflow URL. Supports multiple values.

​
workflowRunId
string

Filter by workflow run ID.

​
workflowCreatedAt
integer<int64>

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

​
label
string[]

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
​
failureFunctionState
string[]

Filter by failure function state. Supports multiple values.

StateDescription
CALLBACK_INPROGRESSThe failure function is in progress.
CALLBACK_SUCCESSThe failure function run successfully.
CALLBACK_FAILThe failure function failed to run.
CALLBACK_CANCELEDThe failure function was manually canceled
​
callerIp
string[]

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

​
flowControlKey
string[]

Filter by Flow Control Key. Supports multiple values.

Response

List of failed workflow runs

​
cursor
string

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

​
messages
object[]

Array of failed workflow messages.