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

# List prospects

`GET /prospects`

## Request

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

Returns prospects in your workspace, newest first, with cursor pagination. Pass listId to return only the prospects in one list — the way to pull everyone in a list from your own server or script. Get list ids from GET /lists. Pass field and fieldValue to keep only the prospects whose job title, company, country, city or one of your own CSV columns contains a value — the same "Filter by field" as the Prospects page.

Required scope: `prospects:read`.

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

To export a whole list, keep requesting with cursor set to the previous next_cursor until has_more is false.

listId and filter combine: listId narrows to the list, then each filter must also match.

field + fieldValue combines with listId and filter, and is applied before paging, so it never shortens a page. Example: listId=<your list>&field=custom:language&fieldValue=German returns everyone in that list whose Language column contains German.

Every page holds limit rows unless it is the last one. The one exception: with a very selective filter, if 20,000 prospects are checked before the page fills, the page comes back with fewer rows (possibly none) and has_more true. Pass next_cursor back to continue.

## Query parameters

- `limit` integer
- `cursor` string
- `listId` string
- `field` string
- `fieldValue` string
- `fieldMatch` string
- `filter` string

## Response `200`

Success

## Other responses

- `400`: `validation_error` — listId was empty, repeated, or longer than 128 characters; or field / fieldValue was given without the other, field is not one of the fields listed above, or fieldValue is longer than 200 characters; or fieldMatch is not contains or not_contains.
- `401`: `unauthorized` — Missing or invalid API key.
- `403`: `insufficient_scope` — The API key lacks the scope this endpoint requires.
- `404`: `list_not_found` — listId is not a list in your workspace. No prospects are returned.
- `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)