List workflow runs in the DLQ

List and paginate through all failed workflow runs currently inside the DLQ

GET /v2/workflows/dlq

curl https://qstash.upstash.io/v2/workflows/dlq \
  -H "Authorization: Bearer <token>"

200 OK

{
   "cursor":"1752570296426-0",
   "messages":[
      {
         "messageId":"msg_26hZCxZCuWyyTWPmSVBrNC1RADwpgWxPcak2rQD51EMjFMuzcW7qYXpPiDyw8Gd",
         "url":"https://my.app/workflow",
         "method":"POST",
         "header":{
            "Content-Type":[
               "application/json"
            ]
         },
         "maxRetries":10,
         "notBefore":1752829294505,
         "createdAt":1752829294505,
         "failureCallback":"https://my.app/workflow",
         "callerIP":"88.240.188.2",
         "workflowRunId":"wfr_5XAx4IJergqkGK1v23VzR",
         "workflowCreatedAt":1752829293531,
         "workflowUrl":"https://my.app/workflow",
         "responseStatus":489,
         "responseHeader":{
            "Content-Type":[
               "text/plain;charset=UTF-8"
            ]
         },
         "responseBody":"{\"error\":\"WorkflowNonRetryableError\",\"message\":\"this workflow has stopped\"}",
         "failureCallbackInfo":{
            "state":"CALLBACK_SUCCESS",
            "responseStatus":200,
            "responseBody":"{\"workflowRunId\":\"wfr_Q_khHG-a414M-xKRh2kNI\"}",
            "responseHeaders":{
               "Content-Type":[
                  "text/plain;charset=UTF-8"
               ]
            }
         },
         "dlqId":"1752829295505-0"
      }
   ]
}

List all failed workflow runs currently inside the Dead Letter Queue.

Request

cursor · string

By providing a cursor you can paginate through all of the workflow runs in the DLQ

workflowRunId · string

Filter DLQ workflow runs by workflow run id.

workflowUrl · string

Filter DLQ workflow runs by workflow url.

fromDate · number

Filter DLQ workflow runs by starting date, in milliseconds (Unix timestamp). This is inclusive.

toDate · number

Filter DLQ workflow runs by ending date, in milliseconds (Unix timestamp). This is inclusive.

responseStatus · number

Filter DLQ workflow runs by HTTP response status code.

callerIP · string

Filter DLQ workflow runs by IP address of the publisher.

failureCallbackState · string

Filter DLQ workflow runs by the state of failure callback (failure function or failure URL)

count · number

The number of workflow runs to return. Default and maximum is 100.

label · string

Filter workflow run by the label assigned by the user.

Response

cursor · string

A cursor which you can use in subsequent requests to paginate through all workflow runs. If no cursor is returned, you have reached the end of the workflow runs.

messages · Array

Hide message

messageId · string · required

Unique identifier for the DLQ message.

url · string

The URL of the workflow endpoint.

method · string

HTTP method used for the request.

header · object

Initial request headers for workflow run, including the configuration headers.

body · string

Request payload of the workflow run (if UTF-8).

bodyBase64 · string

Request body (base64-encoded, if not UTF-8).

maxRetries · integer

Maximum number of retries for the workflow run.

notBefore · integer

Earliest time (Unix ms) the message could be processed.

createdAt · integer

Timestamp (Unix ms) when the message was created.

failureCallback · string

Failure callback URL (if set).

failureCallbackHeader · object

Failure callback request headers.

callerIP · string

IP address of the publisher.

workflowRunId · string

Workflow run ID (if applicable).

workflowCreatedAt · integer

Timestamp (Unix ms) when the workflow run was created.

workflowUrl · string

Workflow URL.

flowControlKey · string

Flow control key (if set).

rate · integer

Rate limit (if set).

parallelism · integer

Parallelism (if set).

period · integer

Period (if set).

responseStatus · integer

HTTP response status code of the last failed delivery attempt.

responseHeader · object

HTTP response headers of the last failed delivery attempt.

responseBody · string

HTTP response body (if UTF-8).

responseBodyBase64 · string

HTTP response body (base64-encoded, if not UTF-8).

failureCallbackInfo · object

Detailed information about the failure callback, including state, response body, response status and response headers.

label · string

The label of the run assigned by the user.

curl https://qstash.upstash.io/v2/workflows/dlq \
  -H "Authorization: Bearer <token>"

200 OK

{
   "cursor":"1752570296426-0",
   "messages":[
      {
         "messageId":"msg_26hZCxZCuWyyTWPmSVBrNC1RADwpgWxPcak2rQD51EMjFMuzcW7qYXpPiDyw8Gd",
         "url":"https://my.app/workflow",
         "method":"POST",
         "header":{
            "Content-Type":[
               "application/json"
            ]
         },
         "maxRetries":10,
         "notBefore":1752829294505,
         "createdAt":1752829294505,
         "failureCallback":"https://my.app/workflow",
         "callerIP":"88.240.188.2",
         "workflowRunId":"wfr_5XAx4IJergqkGK1v23VzR",
         "workflowCreatedAt":1752829293531,
         "workflowUrl":"https://my.app/workflow",
         "responseStatus":489,
         "responseHeader":{
            "Content-Type":[
               "text/plain;charset=UTF-8"
            ]
         },
         "responseBody":"{\"error\":\"WorkflowNonRetryableError\",\"message\":\"this workflow has stopped\"}",
         "failureCallbackInfo":{
            "state":"CALLBACK_SUCCESS",
            "responseStatus":200,
            "responseBody":"{\"workflowRunId\":\"wfr_Q_khHG-a414M-xKRh2kNI\"}",
            "responseHeaders":{
               "Content-Type":[
                  "text/plain;charset=UTF-8"
               ]
            }
         },
         "dlqId":"1752829295505-0"
      }
   ]
}