---
title: "List DLQ messages"
method: GET
path: "/v2/dlq"
tags: ["DLQ"]
---

# List DLQ messages

`GET /v2/dlq`

## Request

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

List and paginate through all messages currently in the DLQ

## Query parameters

- `cursor` string
- `messageId` string
- `url` string[]
- `topicName` string[]
- `scheduleId` string[]
- `queueName` string[]
- `fromDate` integer
- `toDate` integer
- `responseStatus` integer[]
- `callerIp` string[]
- `label` string[]
- `count` integer

## Response `200`

List of DLQ messages

- object
  - `cursor` string: A cursor which you can use in subsequent requests to paginate through all messages. If no cursor is returned, you have reached the end of the messages.
  - `messages` DLQMessage[]
    - `messageId` string: Unique identifier for the message
    - `url` string: The URL to which the message should be delivered.
    - `topicName` string: The URL Group (a.k.a. topic) name if this message was sent to a URL Group.
    - `endpointName` string: The endpoint name of the message if the endpoint is given a name within the URL group.
    - `method` string: The HTTP method to use for the message.
    - `header` object: The HTTP headers sent to your API.
    - `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.
    - `notBefore` integer: The unix timestamp in milliseconds before which the message should not be delivered.
    - `createdAt` integer: The unix timestamp in milliseconds when the message was created.
    - `callback` string: The url where we send a callback each time the message is attempted to be delivered.
    - `failureCallback` string: The url where we send a callback to after the message is failed
    - `queueName` string: The name of the queue if the message is enqueued to a queue.
    - `scheduleId` string: The scheduleId of the message if the message is triggered by a schedule
    - `callerIP` string: IP address of the publisher of this message.
    - `label` string: The label of the message assigned by the user. Deprecated in favor of `labels`.
    - `labels` string[]: The list of labels assigned to the message by the user.
    - `flowControlKey` string: The flow control key used for rate limiting.
    - `rate` integer: The rate value used for flow control.
    - `period` integer: The period value used for flow control.
    - `parallelism` integer: The parallelism value used for flow control.
    - `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.

## Changes

- **2026-06-25** `9bff0f72df49`: 6 info
  - for the `query` request parameter `callerIp`, the type was generalized from `string` to `array`
  - for the `query` request parameter `queueName`, the type was generalized from `string` to `array`
  - for the `query` request parameter `responseStatus`, the type was generalized from `integer` to `array`
  - for the `query` request parameter `scheduleId`, the type was generalized from `string` to `array`
  - …2 more
- **2026-06-09** `d30bd0904328`: 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
- **2026-06-09** `d859c277ced2`: 1 warning, 2 info
  - removed the optional property `messages/items/labels` from the response with the `200` status
  - for the `query` request parameter `label`, the type was generalized from `array` to `string`
  - response property `messages/items/label` reactivated
- **2026-05-15** `75ecd1c6fb73`: 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
- **2026-03-17** `4ef567cf4b77`: 1 warning
  - deleted the `query` request parameter `order`

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

---

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