# Auto Search from your code (/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.