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

# Async Person Search

> Submit a natural-language person search for asynchronous full-segment materialization

<div style={{ display: 'none' }} aria-hidden="false">
  ## Quick Answer

  **How do I run a large person search asynchronously?** Submit the audience description here, poll the returned `segment_id` until the job is `completed`, then unlock and page its PIDs through the results endpoint.

  **What you get back:** A `segment_id` that identifies both the async job and its materialized segment.
</div>

## Overview

Async Person Search builds a complete, reusable segment from a natural-language
audience description. The submission returns immediately with `202 Accepted`;
parsing and full result materialization continue in the background.

The complete workflow is:

1. `POST /person-search/v0/search-jobs` to submit the query.
2. Poll [Async Person Search Status](/api-reference/person-search-job-status)
   until `status` is `completed`.
3. Inspect `total_count` and `estimated_billable_count` before unlocking.
4. `POST .../{segment_id}/results` once to unlock the entire segment and
   return the first requested PID page.
5. Use `GET .../{segment_id}/results` for subsequent pages without re-billing.

<Note>
  Unlike synchronous [Person Search](/api-reference/person-search), the submit
  response does not contain PIDs. Async search fully materializes the segment
  first, then returns PIDs only after the explicit results unlock.
</Note>

## Authentication requirement

The API key must be associated with a Minerva user. Organization-only API keys
without a user association cannot create or access async person-search jobs and
receive `401 Unauthorized`.

<RequestExample>
  ```bash Submit a search theme={null}
  curl --request POST \
    --url 'https://api.minerva.io/person-search/v0/search-jobs' \
    --header 'x-api-key: <api-key>' \
    --header 'Content-Type: application/json' \
    --data '{
      "query": "Software engineers in Austin who previously worked at a public technology company"
    }'
  ```
</RequestExample>

## Request

### Headers

<ParamField header="x-api-key" type="string" required>
  A user-associated API key.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  `application/json`
</ParamField>

### Request Body

<ParamField body="query" type="string" required>
  Natural-language audience description. Must contain between `1` and `500`
  characters.
</ParamField>

## Response

### Success Response (`202 Accepted`)

<ResponseField name="segment_id" type="string">
  UUID identifying both the async search job and its materialized segment.
</ResponseField>

<ResponseField name="status" type="string">
  Initial job status. Normally `created`.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO-8601 submission timestamp.
</ResponseField>

```json 202 theme={null}
{
  "segment_id": "8c2a6f71-3d41-4fc5-a2b6-1f53a5c81d77",
  "status": "created",
  "created_at": "2026-07-21T20:00:00.000000Z"
}
```

## Errors

| Status | When                                                                          |
| ------ | ----------------------------------------------------------------------------- |
| `401`  | Missing/invalid credentials, or the API key has no associated user            |
| `403`  | The authenticated principal or billing tier cannot use this route             |
| `422`  | `query` is missing, empty, longer than 500 characters, or the body is invalid |
| `429`  | Request-rate or plan quota exceeded                                           |
| `503`  | The segment materialization service is temporarily unavailable                |

## Related

* [Async Person Search Status](/api-reference/person-search-job-status)
* [Async Person Search Results](/api-reference/person-search-job-results)
* [Synchronous Person Search](/api-reference/person-search)