# The Prospects and intent leads API (Scale plan)

> On the Scale plan, the REST API can describe, preview, build and page intent audiences, save them to prospect lists, and search and reveal the Prospects table. Who can use it, the endpoints, and the fair-use limits: up to 5,000,000 audience contacts a day and per-minute and per-hour limits on searches.

Source: https://emailpal.io/help/prospects-and-intent-leads-api

## Who can use it

API access to intent audiences and Prospects search is part of the **Scale** plan only. It uses the same API keys as the rest of the REST API. [Create an API key](/help/create-an-api-key)

- Without an active subscription, the endpoints answer **402** `subscription_required`.
- On Starter or Growth, they answer **403** `plan_required`. Upgrade in **Billing** to use them.

On every plan you can still build audiences in the dashboard, and the rest of the API (campaigns, leads, prospect lists, verification) works as usual. [Build an intent audience](/help/build-an-intent-audience)

## Intent audience endpoints

All paths are under `/api/public/v1`. The [API documentation](/docs) has the request and response bodies.

| Endpoint | What it does |
| --- | --- |
| `POST /audiences/describe` | Turns a sentence into filters and interest topics you can preview |
| `GET /audiences/segments?q=` | Searches the interest-topic catalog |
| `POST /audiences/preview` | How many people match, and a sample. Free; builds nothing |
| `POST /audiences` | Builds an audience (up to 50,000 people) |
| `GET /audiences` | Lists your audiences |
| `GET /audiences/{id}` | One audience and its status. Poll it until the rows are ready |
| `GET /audiences/{id}/records` | One page of an audience's people, up to 1,000 per page |
| `POST /audiences/{id}/add-to-list` | Saves the audience into a new or existing prospect list, in the background |
| `GET /audiences/{id}/import?list_id=` | Progress of that import |
| `DELETE /audiences/{id}` | Deletes an audience. Lists already filled from it keep their people |

The same rules as the dashboard apply: the server re-runs the preview before it builds, an audience over 50,000 people is refused with **400** `too_big`, an empty one with `empty_audience`, and a city without a state with `city_needs_state`. Every person saved to a list passes your suppressions and the removal list first.

## Prospects table endpoints

| Endpoint | What it does |
| --- | --- |
| `POST /prospects/search` | Searches people, with masked rows and record ids, as the dashboard does |
| `POST /prospects/companies` | Searches companies |
| `POST /prospects/reveal` | Reveals the contact details of 1 to 50 people from a search |

If the Prospects table is not available on the current data source, these answer **409** `source_unavailable`; use the intent audience endpoints instead.

## Fair-use limits

The API has fair-use limits per account, so it stays fast for everyone:

| What | Limit |
| --- | --- |
| Audience contacts built through the API | **5,000,000 per day** (resets at 00:00 UTC) |
| Preview and describe (shared) | 60 a minute and 1,000 an hour |
| Prospects search (people and companies, shared) | 60 a minute and 1,500 an hour |
| Building audiences | 10 a minute and 200 an hour |
| Reveals | 30 requests a minute, shared with the dashboard |

The daily allowance counts the people in each audience you build through the API, at the size the server previewed. An audience that would pass it is refused with **429** `api_daily_contacts_limit`, and the message says how many are left today.

A request over a per-minute or per-hour limit gets **429** with a `Retry-After` header (seconds) and a `code` that names the limit, for example `preview_minute_limit`, `search_hour_limit`, `generate_minute_limit` or `reveal_minute_limit`. Wait that long and retry.

## FAQs

### Is the API included in the Scale price?

Yes. There is no separate fee and no per-lead charge.

### Can an AI agent use it?

Yes, with a Scale plan API key, over the REST API. See [MCP server and REST API](/help/mcp-server-and-rest-api) for connecting an agent.

### Do audiences built through the API show in the dashboard?

Yes. They appear in **Your audiences** in Prospects, and lists filled from them appear in **Prospects, Lists**.

## Need More Help?

[API documentation](/docs), [Unlimited intent leads: what is included](/help/unlimited-intent-leads), or [open a ticket](/support/new).