Get a failed workflow run from the DLQ

Get a single failed workflow run from the DLQ

GET /v2/workflows/dlq/{dlqId}

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

200 OK

{
  "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 a single failed workflow run from the Dead Letter Queue (DLQ).

Request

dlqId · string

The DLQ id of the failed workflow run you want to retrieve. You will see this id when listing all workflow runs in the DLQ with the /v2/workflows/dlq endpoint.

Response

If the workflow run is not found in the DLQ (either it has already been removed by you, or automatically), the endpoint returns a 404 status code.

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 -X GET https://qstash.upstash.io/v2/workflows/dlq/my-dlq-id \
  -H "Authorization: Bearer <token>"

200 OK

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