List Failed Workflow Runs - Upstash Documentation

GET/v2/workflows/dlq

cURL

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

200Response

{
  "cursor": "<string>",
  "messages": [
    {
      "dlqId": "<string>",
      "workflowUrl": "<string>",
      "workflowRunId": "<string>",
      "workflowCreatedAt": 123,
      "url": "<string>",
      "method": "<string>",
      "header": "<string>",
      "body": "<string>",
      "bodyBase64": "<string>",
      "maxRetries": 123,
      "createdAt": 123,
      "failureCallback": "<string>",
      "callerIP": "<string>",
      "label": "<string>",
      "labels": [
        "<string>"
      ],
      "flowControlKey": "<string>",
      "failureFunctionState": "<string>",
      "responseStatus": 123,
      "responseHeader": "<string>",
      "responseBody": "<string>",
      "responseBodyBase64": "<string>"
    }
  ]
}

Authorization

Authorizationheaderstringrequired

Bearer authentication header of the form Bearer <token>.

Query parameters

cursorquerystring

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

countqueryintegerdefault: 100

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

fromDatequeryinteger

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

toDatequeryinteger

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

workflowUrlquerystring[]

Filter by workflow URL. Supports multiple values.

workflowRunIdquerystring

Filter by workflow run ID.

workflowCreatedAtqueryinteger

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

labelquerystring[]

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

failureFunctionStatequerystring[]

Filter by failure function state. Supports multiple values.

State	Description
CALLBACK_INPROGRESS	The failure function is in progress.
CALLBACK_SUCCESS	The failure function run successfully.
CALLBACK_FAIL	The failure function failed to run.
CALLBACK_CANCELED	The failure function was manually canceled

callerIpquerystring[]

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

flowControlKeyquerystring[]

Filter by Flow Control Key. Supports multiple values.

Response

200 — List of failed workflow runs

cursorstring

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

messagesobject[]

Array of failed workflow messages.

dlqIdstring

The DLQ ID of the failed workflow message.

workflowUrlstring

The URL of the workflow.

workflowRunIdstring

The ID of the workflow run.

workflowCreatedAtinteger

The timestamp when the workflow run was created (Unix timestamp in milliseconds).

urlstring

The URL of the failed workflow step.

methodstring

The HTTP method used for the workflow step.

headerobject

The HTTP headers sent to the workflow step.

bodystring

The body of the message if it is composed of utf8 chars only, empty otherwise.

bodyBase64string

The base64 encoded body if the body contains a non-utf8 char only, empty otherwise.

maxRetriesinteger

The number of retries that should be attempted in case of delivery failure.

createdAtinteger

The unix timestamp in milliseconds when the message was created.

failureCallbackstring

The url where we send a callback to after the workflow fails.

callerIPstring

IP address of the publisher of this workflow.

labelstringdeprecated

The label assigned to the workflow run. Deprecated in favor of labels.

labelsstring[]

The list of labels assigned to the workflow run.

flowControlKeystring

The flow control key used for rate limiting.

failureFunctionStatestring

The state of the failure function if applicable.

responseStatusinteger

The HTTP status code received from the destination API.

responseHeaderobject

The HTTP response headers received from the destination API.

responseBodystring

The body of the response if it is composed of utf8 chars only, empty otherwise.

responseBodyBase64string

The base64 encoded body of the response if the body contains a non-utf8 char only, empty otherwise.

400 — Bad Request

errorstringrequired

Error message

401 — Unauthorized

errorstringrequired

Error message

500 — Internal Server Error

errorstringrequired

Error message