---
title: "List prospect lists"
method: GET
path: "/lists"
tags: ["Prospects"]
---

# List prospect lists

`GET /lists`

## Request

- Base URL: `https://warmysender.com/api/v1`
- URL: `https://warmysender.com/api/v1/lists`
- Auth: HTTP bearer

Returns the lists in your workspace, newest first, with cursor pagination. Each list includes its id, name and how many prospects it holds. Use a list id with GET /prospects?listId=<id> to pull the prospects in that list.

Required scope: `prospects:read`.

Returns a cursor-paginated list — pass `cursor` from the previous page to continue.

prospectCount counts the prospects GET /prospects?listId=<id> returns for that list.

Prospects that are in no list are not a list, so they do not appear here. Fetch them with GET /prospects?listId=__unassigned__.

## Query parameters

- `limit` integer
- `cursor` string

## Response `200`

Success

## Other responses

- `401`: `unauthorized` — Missing or invalid API key.
- `403`: `insufficient_scope` — The API key lacks the scope this endpoint requires.
- `429`: `rate_limited` — Too many requests — slow down and retry after the Retry-After delay.

---

[API](https://skmtc.dev/warmysender/apis/warmysender-public-api.md) · [All operations](https://skmtc.dev/warmysender/apis/warmysender-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/warmysender/apis/warmysender-public-api/revisions/eb5c7f10a1cd?raw)