Skip to main content
GET
List leads

Authorizations

Authorization
string
header
required

A ManyPI API key (mpi_...) from the profile menu → API Access in the dashboard, or an OAuth 2.1 access token obtained through the MCP consent flow.

Query Parameters

q
string

Free text across company, full name, email and domain.

status
enum<string>

A lifecycle status. archived and unsubscribed are still accepted as older spellings of archived=only and subscribed=unsubscribed.

Available options:
new,
qualified,
contacted,
disqualified,
archived,
unsubscribed
campaign
string<uuid>

The run id of a lead search: the run_id that POST /api/leads/research returns, or the id of any agent run that saved leads. Returns only the leads that search saved. campaigns in the GET /api/leads response lists the lead searches that have saved leads. A malformed id is ignored, so the request then returns every lead.

brand
string

Narrow to one brand by its id. Leave it out, or send all, for every brand you can reach. Leads with no brand are always included.

subscribed
enum<string>

Opt-out state, separate from status.

Available options:
subscribed,
unsubscribed
archived
enum<string>
default:hide

hide leaves archived leads out, show includes them, only returns nothing else.

Available options:
hide,
show,
only
owner
string

unassigned, or a workspace member's user id.

list
string<uuid>

Only the leads in this lead list.

import
string<uuid>

Only the leads one import created (import_id from POST /api/leads/import).

missing
string

Comma-separated keys, at most 20. Only leads where at least one of these core or custom fields is empty.

one_per_company
enum<string>

Keep only the best-ranked contact at each company. Leads with no company are always kept.

Available options:
true,
1
not_in_campaign
string<uuid>

Leave out leads an outreach campaign holds or has mailed.

filter
string

A filter tree as JSON, the same one the leads grid builds.

tzo
integer

Your timezone offset in minutes, for date filters in filter.

meta
enum<string>

Send 0 for rows only: workspaceTotal and campaigns are left out, which is faster when paging.

Available options:
0
runs
enum<string>

Send 0 to leave out campaigns only.

Available options:
0
limit
integer
default:100

Max 500.

Required range: x <= 500
offset
integer
default:0

Response

Leads and grid metadata.

leads
object[]
total
integer

Rows matching the current filter.

workspaceTotal
integer

Every lead the workspace stores, ignoring filters. Left out under meta=0.

customColumns
string[]
customFields
object[]
campaigns
object[]

The lead searches that saved leads, newest first, with how many leads each saved. Pass an id as campaign to list its leads. Left out under meta=0 or runs=0.

leadLimit
integer

Stored-lead cap for the plan.

manualLeadLimit
integer

How many leads a person may add by import or by hand. Higher than leadLimit on Free.

filterCapped
boolean

Present, and true, only when the filter was checked against the newest rows rather than all of them.

billingLock
object | null

Present only when the workspace is locked for billing. leads then holds placeholder rows and total is the number of real leads waiting behind the lock.