List workflow runs in the DLQ - Upstash Documentation

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

{
   "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"
      }
   ]
}

GET

workflows

dlq

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

{
   "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.

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.

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

{
   "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 Flow-Control Keys Get a failed workflow run from the DLQ

Workflow

​Request

​Response

Request

Response