---
title: "List lead searches"
method: GET
path: "/v1/lead-searches"
tags: ["Lead Finder"]
---

# List lead searches

`GET /v1/lead-searches`

## Request

- Base URL: `https://api.mailbeast.ai`
- URL: `https://api.mailbeast.ai/v1/lead-searches`
- Auth: HTTP bearer

Cursor-paginate the workspace’s lead searches (newest-first, stable under concurrent changes) for history and to discover ids to poll. In-progress chat drafts are not listed.

Requires one of the following scopes: `leadfinder:read`, `all:read`, `all:all`.

## Query parameters

- `cursor` string
- `limit` number

## Response `200`

- LeadSearchListApiResponseDto
  - `data` LeadSearchListItemApiDto[], required
    - `id` string, uuid, required
    - `query` string, required: The natural-language query this search was started from.
    - `status` 'draft' | 'queued' | 'discovering' | 'processing' | 'crawling' | 'enriching' | 'verifying' | 'completed' | 'stopped' | 'failed', required: Lifecycle status. Terminal states are `completed`, `stopped`, `failed`; everything else is still running.
    - `searchMode` 'companies' | 'people', required: Whether the search discovers companies or people.
    - `maxResults` number, required: The requested discovery cap for this search.
    - `createdAt` string, date-time, required: When the search was created.
    - `completedAt` string, date-time, nullable: When the search reached a terminal state; null while still running.
  - `meta` LeadSearchListMetaApiDto, required
    - `hasMore` boolean, required: Whether more searches are available after this page.
    - `nextCursor` string, nullable: Pass as `?cursor=` to fetch the next page; null when `hasMore` is false.

## Other responses

- `400`: The request body or parameters failed validation.
- `401`: Missing or invalid API key.
- `403`: The key lacks a required scope, or the plan does not include API access.
- `429`: Rate limit exceeded - retry after the interval in the Retry-After header.

---

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