> ## Documentation Index
> Fetch the complete documentation index at: https://docs.loice.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Lead-search runs

> Start a background search, poll it, continue it or cancel it.

A lead search finds people by criteria, such as job title, location, company, industry,
headcount, seniority and keywords, with no target person known in advance. It can deliver
thousands of results, so it runs **in the background**: you start a run, then poll it.

## 1. Start a run

```bash theme={null}
curl https://app.loice.ai/api/v1/lead-search \
  -H "Authorization: Bearer $LOICE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "filters": {
      "jobTitle": ["Head of Sales"],
      "location": ["Germany"],
      "headcount": ["51-200"]
    },
    "count": 500
  }'
```

The answer comes back at once with the run (`status: "queued"`) and your balance after the
worst case has been reserved. If the balance cannot cover the worst case, the run is refused
uncharged with `reason: "insufficient-credits"`.

One run can be active per workspace at a time. Starting another answers
`409 run_already_active`.

## 2. Poll it

```bash theme={null}
curl https://app.loice.ai/api/v1/lead-search/runs/$RUN_ID \
  -H "Authorization: Bearer $LOICE_API_KEY"
```

Poll every few seconds while `status` is `queued`, `processing` or `cancelling`. A terminal
status (`completed`, `cancelled` or `failed`) carries the final `deliveredCount` and
`creditsCharged`. Results arrive in [pages of 25](/pagination) and stay readable after the run
finishes. Polling is free.

Results are directory-style: name, title, company, location and profile URL, never contact data.
To get a verified email for a result, pass its `linkedinUrl` to `POST /api/v1/find` with
`"mode": "linkedin"`.

## 3. Load more

To continue a finished run, start a new run with `continueFromRunId` set to its id. Leads that
were already delivered are never delivered or billed again.

## Cancel

```bash theme={null}
curl -X POST https://app.loice.ai/api/v1/lead-search/runs/$RUN_ID/cancel \
  -H "Authorization: Bearer $LOICE_API_KEY"
```

* A `queued` run ends `cancelled` at once and charges nothing.
* A `processing` run answers `cancelling` and stops at its next page. Only the leads already
  delivered are charged.
* Cancelling again answers the same; a finished run answers `already-terminal`.

Cancelling is free. For how a run is billed, see [Billing and points](/billing#lead-search-runs).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.