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.

GET /v2/workflows/dlq

List Failed Workflow Runs

cURL

curl --request GET \
  --url https://qstash.upstash.io/v2/workflows/dlq \
  --header 'Authorization: Bearer <token>'

200

{
  "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>",
      "flowControlKey": "<string>",
      "failureFunctionState": "<string>",
      "responseStatus": 123,
      "responseHeader": {},
      "responseBody": "<string>",
      "responseBodyBase64": "<string>"
    }
  ]
}

Authorizations

bearerAuthbearerAuthQuery

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

order · enum<string> · default: earliestFirst

The sorting order of workflow runs by timestamp.

Available options: latestFirst, earliestFirst

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.

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.

failureFunctionState · string

Filter by failure function state.

callerIp · string

Filter by IP address of the publisher.

flowControlKey · string

Filter by Flow Control Key.

Response

200

application/json

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.

Show child attributes