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

# Cancel a people search

> Stops a people search from starting new work.

Results found so far stay readable.

Cancelling stops the search from starting new work. Provider calls already in progress may finish, add results and be charged. The search reaches `status: cancelled` once that work has finished.

Cancelling a search that has already finished returns it unchanged. Cancelling twice costs nothing.

> [!NOTE]
>
> A client timeout or a closed connection does not cancel a search. Call this endpoint to stop spending.

### Path parameters

**search\_id** `string` *required*

The search's `id`, returned when it was started.

### Response

* **`202`** Cancellation was requested. Work already in progress is finishing.
* **`200`** The search had already finished. It is returned unchanged.

**object** `string` *required*

`company_search` or `people_search`.

**id** `string` *required*

The search's identifier. Use it to read status and results.

**status** `string` *required*

`queued` and `running` are in progress. `completed`, `failed` and `cancelled` are terminal. `completed` means this run finished, not that every matching record in the world was found.

**stop\_reason** `string | null` *required*

Why a finished search stopped. `null` while it is in progress. Can also be `null` on a `failed` search; read `error`.

Options: `target_reached`, `sources_exhausted`, `usage_limit_reached`, `retrieval_limit_reached`, `query_needs_clarification`, `provider_failed`, `cancelled`.

**error** `string | null` *required*

A message when `status` is `failed`. Results found before the failure stay readable.

**query** `string | null` *required*

The natural-language request, when the search was started with `query`.

**limit** `integer` *required*

The most results this search will return.

**interpretation** `object | null` *required*

How a `query` was read. `null` until the query has been interpreted, and for searches started with `filters` or `criteria`.

**properties**

**filters** `object`

Structured conditions. A record must meet every condition in `all`. `null` is treated the same as leaving `filters` out. See the [filter reference](https://docs.data.avina.io/guides/structured-filters.md) for every field and operator.

**properties**

**all** `object[]` *required*

The conditions. A record must meet every one. Each item is a field condition (`field`, `operator`, `value`) or a `related` condition.

**item properties**

**field** `string`

The field to test, such as `company.industry` or `person.title`.

**operator** `string`

How to compare. Which operators a field accepts depends on its type.

Options: `in`, `matches`, `eq`, `gt`, `gte`, `lt`, `lte`, `between`, `within_last_days`.

**value** `any`

The value to compare against. A list for `in`, a two-item list for `between`, a `{amount, currency}` object for money fields, a number of days for `within_last_days`.

**related** `object`

A condition on records related to the company. All conditions in `where` must be true of the same record, for example one job listing.

**properties**

**relationship** `string` *required*

`open_jobs`: the company has at least one open job that matches. `new_hires`: someone with a matching title joined the company within the window.

**where** `object` *required*

Conditions on the related record.

**properties**

**all** `object[]` *required*

Conditions on `title` (`in`), `posted_at` (`within_last_days`, for `open_jobs`) or `started_at` (`within_last_days`, for `new_hires`).

**item properties**

**field** `string` *required*

The field on the related record.

Options: `title`, `posted_at`, `started_at`.

**operator** `string` *required*

`in` for `title`; `within_last_days` for `posted_at` and `started_at`.

**value** `any` *required*

A list of titles for `in`, or a whole number of days from 1 to 36500 for `within_last_days`.

**criteria** `object[]`

Free-text requirements read from the query.

**item properties**

**text** `string` *required*

The requirement, written as a statement that is true of a match.

**kind** `string`

`attribute`: a lasting fact the company's own description could state, such as "sells to hospitals". `event`: something that happened, such as "opened a location in Texas this year"; checked by web research.

**unsupported\_criteria** `string[]`

Requirements no public source can confirm, quoted from the query. A search cannot run while there are any.

**errors** `object[]`

Problems validating the filters the query was read as. A search cannot run while there are any.

**item properties**

**field** `string`

The filter path with the problem.

**message** `string` *required*

What is wrong.

**assumptions** `object[]` *required*

Ambiguous wording in the query and how it was read.

**item properties**

**text** `string` *required*

The exact phrase from the query.

**assumed** `string` *required*

The reading that was used.

**alternatives** `string[]` *required*

Other readings. Reword the query if one of these is what you meant.

**progress** `object` *required*

Counts so far. They only increase.

**properties**

**candidates** `integer` *required*

Candidates checked so far.

**accepted** `integer` *required*

Candidates that matched every requirement and were added to the results.

**rejected** `integer` *required*

Candidates that failed at least one requirement.

**unknown** `integer` *required*

Candidates whose evidence could not confirm every requirement. They are not returned.

**not\_returned** `integer` *required*

Candidates that matched every requirement but were not returned because `limit` or a spend limit had already been reached.

**contacts\_found** `integer` *required*

Contacts found so far. For company searches with `persona_ids`, and people searches with enrichment.

**credits\_charged** `number` *required*

Credits charged for this search so far. 1 credit = \$1.00.

**cancel\_requested** `boolean` *required*

`true` after a cancel request, until the search reaches `cancelled`.

**created\_at** `string` *required*

When the search was started.

**completed\_at** `string | null` *required*

When the search reached a terminal status.

**expires\_at** `string | null` *required*

When the search and its results stop being readable. `null` when no expiry is set.

**status\_url** `string` *required*

The URL of this search's status.

**results\_url** `string` *required*

The URL of this search's results.

### Errors

| Status | Code | When |
| - | - | - |
| `401` | `invalid_api_key` | The API key is missing, invalid or revoked. |
| `404` | `not_found` | No such object in this workspace. |
| `429` | `rate_limited` | Too many requests. Retry after `Retry-After` seconds. |
| `500` | `internal_error` | Something went wrong on our side. Retry with backoff, and with the same `Idempotency-Key` if you sent one. |

Every error uses the same shape. See [Errors](https://docs.data.avina.io/api-reference/errors.md).

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://api.avina.io/v1/people/search/$SEARCH_ID/cancel \
  -H "Authorization: Bearer $AVINA_API_KEY"
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import os
import requests

response = requests.post(
    f"https://api.avina.io/v1/people/search/{search_id}/cancel",
    headers={"Authorization": f"Bearer {os.environ['AVINA_API_KEY']}"},
)
response.raise_for_status()
print(response.json())
```

```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const response = await fetch(`https://api.avina.io/v1/people/search/${searchId}/cancel`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.AVINA_API_KEY}`,
  },
});
const data = await response.json();
console.log(data);
```

```json 202 theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "object": "people_search",
  "id": "7c1d9a52-3e0b-4f6a-9d21-5b8e4a7c0f13",
  "status": "running",
  "stop_reason": null,
  "error": null,
  "query": "Heads of revenue operations at US fintech companies with 200 to 1,000 employees",
  "limit": 25,
  "interpretation": {
    "filters": {
      "all": [
        {
          "field": "person.title",
          "operator": "in",
          "value": [
            "Head of Revenue Operations",
            "VP Revenue Operations",
            "Director of Revenue Operations"
          ]
        },
        {
          "field": "company.headquarters.country",
          "operator": "in",
          "value": ["US"]
        },
        {
          "field": "company.industry",
          "operator": "in",
          "value": ["Financial Services"]
        },
        {
          "field": "company.employee_count",
          "operator": "between",
          "value": [200, 1000]
        }
      ]
    },
    "criteria": [],
    "unsupported_criteria": []
  },
  "assumptions": [],
  "progress": {
    "candidates": 22,
    "accepted": 9,
    "rejected": 12,
    "unknown": 1,
    "not_returned": 0,
    "contacts_found": 9
  },
  "credits_charged": 2.3,
  "cancel_requested": true,
  "created_at": "2026-11-12T17:10:02Z",
  "completed_at": null,
  "expires_at": null,
  "status_url": "https://api.avina.io/v1/people/search/7c1d9a52-3e0b-4f6a-9d21-5b8e4a7c0f13/status",
  "results_url": "https://api.avina.io/v1/people/search/7c1d9a52-3e0b-4f6a-9d21-5b8e4a7c0f13/results"
}
```

```json 401 theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key is invalid or revoked.",
    "request_id": "req_8f2a61c09d4e7b3a5f10c2d8"
  }
}
```


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