# client.dlq.list

The `dlq.list` method retrieves messages that were sent to the **Dead Letter Queue (DLQ)**.

DLQ messages represent failed workflow or QStash deliveries that could not be retried successfully.

## Arguments

<ParamField body="cursor" type="string" optional>
    A pagination cursor from a previous request.
    Use this to fetch the next batch of results.
</ParamField>

<ParamField body="count" type="number" optional>
    Maximum number of DLQ messages to return.
    Defaults to a system-defined limit if not provided.
</ParamField>

<ParamField body="filter" type="object" optional>
    Filter options for narrowing down DLQ messages.

    <Expandable defaultOpen>
        <ParamField body="workflowUrl" type="string" optional>
            Filter by exact workflow URL.
        </ParamField>

        <ParamField body="workflowRunId" type="string" optional>
            Filter by workflow run ID.
        </ParamField>

        <ParamField body="label" type="string | string[]" optional>
            Filter by workflow label. Pass an array to match runs that have any
            of the given labels (OR semantics).
        </ParamField>

        <ParamField body="fromDate" type="Date | number" optional>
            Earliest date to include. Accepts `Date` objects or Unix timestamps (ms).
        </ParamField>

        <ParamField body="toDate" type="Date | number" optional>
            Latest date to include. Accepts `Date` objects or Unix timestamps (ms).
        </ParamField>

        <ParamField body="callerIp" type="string" optional>
            Filter by the IP address that triggered the workflow.
        </ParamField>

        <ParamField body="flowControlKey" type="string" optional>
            Filter by flow control key.
        </ParamField>

        <ParamField body="workflowCreatedAt" type="number" optional>
            Filter by workflow creation time (Unix timestamp in ms).
        </ParamField>

        <ParamField body="failureFunctionState" type="string" optional>
            Filter by failure callback state.
        </ParamField>
    </Expandable>
</ParamField>

## Response

<ResponseField name="messages" type="DLQMessage[]">
    An array of DLQ messages that match the provided filters.
</ResponseField>

<ResponseField name="cursor" type="string">
    A cursor to paginate through additional results.
    If not returned, you have reached the end of the DLQ.
</ResponseField>

## Usage

```ts
import { Client } from "@upstash/workflow";

const client = new Client({ token: "<QSTASH_TOKEN>" });

// List all DLQ messages
const { messages, cursor } = await client.dlq.list();

// List with pagination and filtering
const result = await client.dlq.list({
  cursor,
  count: 10,
  filter: {
    fromDate: Date.now() - 86400000, // last 24 hours
    toDate: Date.now(),
    workflowUrl: "https://your-endpoint.com",
    label: "my-workflow",
  }
});
```