---
title: "List Failed Workflow Runs"
method: GET
path: "/v2/workflows/dlq"
tags: ["DLQ"]
---

# List Failed Workflow Runs

`GET /v2/workflows/dlq`

## Request

- Base URL: `https://qstash-eu-central-1.upstash.io`
- URL: `https://qstash-eu-central-1.upstash.io/v2/workflows/dlq`
- Auth: one of:
  - HTTP bearer
  - API key in query parameter `qstash_token`
- TypeScript: <https://skmtc.dev/upstash/apis/upstash-workflow-rest-api/docs/v2/workflows/dlq/get.ts> (a function with typed inputs; its response is checked against the schema)

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.

## Query parameters

- `cursor` string
- `count` integer
- `fromDate` integer
- `toDate` integer
- `workflowUrl` string[]
- `workflowRunId` string
- `workflowCreatedAt` integer
- `label` string[]
- `failureFunctionState` string[]
- `callerIp` string[]
- `flowControlKey` string[]

## Response `200`

List of failed workflow runs

- object
  - `cursor` string: Pagination cursor for the next page. Empty if no more results.
  - `messages` WorkflowDLQMessage[]: Array of failed workflow messages.
    - `dlqId` string: The DLQ ID of the failed workflow message.
    - `workflowUrl` string: The URL of the workflow.
    - `workflowRunId` string: The ID of the workflow run.
    - `workflowCreatedAt` integer: The timestamp when the workflow run was created (Unix timestamp in milliseconds).
    - `url` string: The URL of the failed workflow step.
    - `method` string: The HTTP method used for the workflow step.
    - `header` object: The HTTP headers sent to the workflow step.
    - `body` string: The body of the message if it is composed of utf8 chars only, empty otherwise.
    - `bodyBase64` string: The base64 encoded body if the body contains a non-utf8 char only, empty otherwise.
    - `maxRetries` integer: The number of retries that should be attempted in case of delivery failure.
    - `createdAt` integer: The unix timestamp in milliseconds when the message was created.
    - `failureCallback` string: The url where we send a callback to after the workflow fails.
    - `callerIP` string: IP address of the publisher of this workflow.
    - `label` string: The label assigned to the workflow run. Deprecated in favor of `labels`.
    - `labels` string[]: The list of labels assigned to the workflow run.
    - `flowControlKey` string: The flow control key used for rate limiting.
    - `failureFunctionState` string: The state of the failure function if applicable.
    - `responseStatus` integer: The HTTP status code received from the destination API.
    - `responseHeader` object: The HTTP response headers received from the destination API.
    - `responseBody` string: The body of the response if it is composed of utf8 chars only, empty otherwise.
    - `responseBodyBase64` string: The base64 encoded body of the response if the body contains a non-utf8 char only, empty otherwise.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `500`: Internal Server Error

## Changes

- **2026-06-25** `4fcd7653bd06`: 4 info
  - for the `query` request parameter `callerIp`, the type was generalized from `string` to `array`
  - for the `query` request parameter `failureFunctionState`, the type was generalized from `string` to `array`
  - for the `query` request parameter `flowControlKey`, the type was generalized from `string` to `array`
  - for the `query` request parameter `workflowUrl`, the type was generalized from `string` to `array`
- **2026-05-15** `4cbcb5c2eac1`: 3 info
  - for the `query` request parameter `label`, the type was generalized from `string` to `array`
  - added the optional property `messages/items/labels` to the response with the `200` status
  - response property `messages/items/label` deprecated

[Operation history](https://skmtc.dev/upstash/apis/upstash-workflow-rest-api/changes/v2/workflows/dlq/get.md)

---

[API](https://skmtc.dev/upstash/apis/upstash-workflow-rest-api.md) - [All operations](https://skmtc.dev/upstash/apis/upstash-workflow-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/upstash/apis/upstash-workflow-rest-api/revisions/251bee05a7ec?raw)