---
title: "Get a lead search"
method: GET
path: "/v1/lead-searches/{id}"
tags: ["Lead Finder"]
---

# Get a lead search

`GET /v1/lead-searches/{id}`

## Request

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

One search’s status and live progress counters (companies found, companies processed, emails found) – the single target to poll while a run is in flight.

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

## Path parameters

- `id` string, uuid, required

## Response `200`

- LeadSearchApiDto
  - `id` string, uuid, required
  - `query` string, required
  - `status` 'draft' | 'queued' | 'discovering' | 'processing' | 'crawling' | 'enriching' | 'verifying' | 'completed' | 'stopped' | 'failed', required
  - `searchMode` 'companies' | 'people', required
  - `maxResults` number, required
  - `discoveryFinished` boolean, required: Whether the discovery phase has finished (crawl/enrich may still run).
  - `progress` LeadSearchProgressApiDto, required
    - `companiesFound` number, required: Companies discovered so far.
    - `companiesProcessed` number, required: Of the discovered companies, how many have finished contact processing (crawled for emails/phones – including those with nothing found). Grows toward `companiesFound` as the run progresses.
    - `emailsFound` number, required: Email addresses discovered so far.
  - `errorMessage` string, nullable: Failure reason when `status` is `failed`; otherwise null.
  - `createdAt` string, date-time, required
  - `updatedAt` string, date-time, required: When the search row was last updated.
  - `completedAt` string, date-time, nullable: When the search reached a terminal state; null while still running.

## 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.
- `404`: The resource does not exist in your workspace.
- `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)