# Auto Search

> Describe your ideal customer once; new matching people are added to your leads every day.

Every section below does the same job: in the dashboard (Guide), from your code (API) or through an AI assistant (MCP).

## Guide — In the dashboard

Source: /docs/leads/prospector/search-prospects/auto-search

Auto Search keeps prospecting for you. Describe who you sell to, check the profile it builds, pick how many leads you want a day. Each lead delivered costs **1 credit**. Pause it any time.

<DemoFrame guide="prospector-auto" to="/identify/{workspace}?tab=prospector" />

1. **Leads → Prospector → + New Auto Search.**
2. **Describe your ideal customer** in plain words, or start from one of your Qualify ICPs.
3. **Review the profile:** each preference is **Must**, **High**, **Prefer** or **Bonus**; the pool shows how many people match.
4. **Pick leads per day**, then **Start Auto Search**.

Already have filters in [Manual search](/docs/leads/prospector/search-prospects/manual-search)? **Save as Auto Search** turns them into one.

### Every control on this screen [#every-control-on-this-screen]

Every button, field and switch, with what it does.

<ScreenControls screens={["leads-autosearch-drawer"]} />


---

## API — From your code

Source: /docs/leads/prospector/search-prospects/auto-search/api

REST endpoints on `https://rest-admin.happierleads.com`, authenticated with `?privateKey=YOUR_KEY` (see [Authentication](/docs/authentication)). A website key only reaches its own website’s Auto Searches.

| Endpoint | Does | Cost |
| --- | --- | --- |
| `POST /admin/prospector/auto-searches/profile` | Turns a description into preferences (nothing saved) | Free |
| `POST /admin/prospector/auto-searches` | Creates and starts an Auto Search | 1 credit per lead delivered |
| `GET /admin/prospector/auto-searches?websiteId=` | Lists a website’s Auto Searches | Free |
| `POST /admin/prospector/auto-searches/{id}/pause` · `/resume` | Stops or restarts deliveries | Free |

<Endpoints ops={["GET /admin/prospector/auto-searches", "POST /admin/prospector/auto-searches/profile", "POST /admin/prospector/auto-searches", "POST /admin/prospector/auto-searches/{autoSearchId}/{action}"]} />

<ApiPlayground
  ops={["GET /admin/prospector/auto-searches", "POST /admin/prospector/auto-searches/profile", "POST /admin/prospector/auto-searches", "POST /admin/prospector/auto-searches/{autoSearchId}/{action}"]}
  path="/admin/prospector/auto-searches/profile"
  tool="build_auto_search_profile"
  args={`{
  "websiteId": "64b7f0a1c2d3e4f5a6b7c8d9",
  "description": "Founders and CEOs of US SaaS companies with 10-200 employees"
}`}
/>

### Use case: describe who you sell to [#use-case-describe-who-you-sell-to]

`POST /admin/prospector/auto-searches/profile` with a sentence or two. You get preferences back: `field`, `values` and `weight` (`Must` is required, `High`, `Prefer` and `Bonus` raise the score).

```json title="Response"
{
  "httpStatus": 200,
  "name": "My ideal customers",
  "prefs": [
    { "field": "job", "values": ["Founder", "CEO"], "weight": "Must" },
    { "field": "industry", "values": ["Computer Software"], "weight": "High" },
    { "field": "hq", "values": ["United States"], "weight": "Must" },
    { "field": "emp", "values": ["11-50", "51-200"], "weight": "Prefer" }
  ]
}
```

### Use case: start it [#use-case-start-it]

`POST /admin/prospector/auto-searches` with a `name`, the `prefs` and `perDay` (25, 50, 100, 200 or 500). It starts straight away; each lead delivered costs **1 credit**.

```bash
curl -X POST "https://rest-admin.happierleads.com/admin/prospector/auto-searches?privateKey=YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "websiteId": "64b7f0a1c2d3e4f5a6b7c8d9", "name": "US SaaS founders", "perDay": 50,
        "prefs": [{ "field": "job", "values": ["Founder", "CEO"], "weight": "Must" }] }'
```

### Use case: check and pause it [#use-case-check-and-pause-it]

`GET /admin/prospector/auto-searches?websiteId=…` lists them with `status`, `deliveredToday`, `deliveredTotal` and `pool` (how many people match). `POST /admin/prospector/auto-searches/{id}/pause` with `{ "websiteId": … }` stops deliveries; `/resume` starts them again.

### When it fails [#when-it-fails]

`401` missing or wrong key, `403` plan without Prospector, `404` not an Auto Search of this website, `422` the description could not be turned into preferences.


---

## MCP — AI agents

Source: /docs/leads/prospector/search-prospects/auto-search/mcp

<Tools names={["list_auto_searches", "build_auto_search_profile", "create_auto_search", "pause_auto_search", "resume_auto_search"]} />

Connect the [MCP server](/docs/mcp#quickstart), then describe who you sell to. Your assistant builds the profile, shows it to you, and starts it when you say so. Each lead delivered costs 1 credit.

### Use case: set one up [#use-case-set-one-up]

> Find me 50 new US SaaS founders every day.

<McpToolCall name="build_auto_search_profile">

```json
{ "websiteId": "64b7f0a1c2d3e4f5a6b7c8d9", "description": "Founders and CEOs of US SaaS companies" }
```

</McpToolCall>

It shows you the preferences (Must, High, Prefer, Bonus), then, once you agree:

<McpToolCall name="create_auto_search">

```json
{
  "websiteId": "64b7f0a1c2d3e4f5a6b7c8d9",
  "name": "US SaaS founders",
  "perDay": 50,
  "prefs": [
    { "field": "job", "values": ["Founder", "CEO"], "weight": "Must" },
    { "field": "hq", "values": ["United States"], "weight": "Must" },
    { "field": "industry", "values": ["Computer Software"], "weight": "High" }
  ]
}
```

</McpToolCall>

### Use case: how is it doing? [#use-case-how-is-it-doing]

> How many leads did my Auto Searches bring in today?

It calls `list_auto_searches` and reads `deliveredToday`, `deliveredTotal` and `pool` for each one.

### Use case: pause it [#use-case-pause-it]

> Pause the US SaaS founders search.

It finds the id with `list_auto_searches`, then calls `pause_auto_search`. `resume_auto_search` starts it again. Turn on tool approval in your assistant to confirm `create_auto_search` and `resume_auto_search`, the calls that start spending credits.