> ## 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 Status

> Poll async person-search processing, inspect the criteria tree, and estimate unlock size

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

  **How do I know when an async person search is ready?** Poll with the
  `segment_id` returned at submission until `status` is `completed`. At
  completion, `total_count` reports the full segment size and
  `estimated_billable_count` provides the pre-unlock billing upper bound.
</div>

## Overview

Returns the current processing state for an async person search owned by your
organization. Poll every 2–5 seconds until the job reaches a terminal status.
Polling does not unlock PIDs and does not incur PID billing.

### Status values

| Status           | Meaning                                                                                    |
| ---------------- | ------------------------------------------------------------------------------------------ |
| `created`        | Accepted and waiting to begin                                                              |
| `initiated`      | Processing has started                                                                     |
| `parsing_search` | The natural-language query is being parsed                                                 |
| `building_query` | Structured search filters are being compiled                                               |
| `querying`       | Matching PIDs are being materialized into the segment                                      |
| `completed`      | Full segment materialization is complete                                                   |
| `failed`         | Terminal processing failure                                                                |
| `cancelled`      | Processing was cancelled                                                                   |
| `previewed`      | A preview-only segment state; not normally returned for this full-materialization endpoint |

### Count and billing fields

* `total_count` is the exact number of PIDs in the completed materialization.
  It is `null` until the count is available.
* `estimated_billable_count` is an **upper bound** before organization-level
  PID deduplication. It normally equals `total_count`.
* `billable_count` is the exact net-new PID count charged during unlock. It is
  `null` before unlock and may be lower than `estimated_billable_count`.
* `results_unlocked` becomes `true` after the current materialization is
  successfully unlocked.

<Warning>
  The billing estimate is for the entire segment, not one results page. A later
  unlock charges all net-new PIDs in the segment even if the first requested
  page contains only one PID.
</Warning>

<RequestExample>
  ```bash Poll status theme={null}
  curl --request GET \
    --url 'https://api.minerva.io/person-search/v0/search-jobs/8c2a6f71-3d41-4fc5-a2b6-1f53a5c81d77' \
    --header 'x-api-key: <api-key>'
  ```
</RequestExample>

## Request

### Headers

<ParamField header="x-api-key" type="string" required>
  The user-associated API key that submitted the search.
</ParamField>

### Path Parameters

<ParamField path="segment_id" type="string" required>
  UUID returned by [Async Person Search](/api-reference/person-search-job-submit).
</ParamField>

## Response

### Success Response (`200 OK`)

<ResponseField name="segment_id" type="string">
  Async search and segment UUID.
</ResponseField>

<ResponseField name="status" type="string">
  Current processing status.
</ResponseField>

<ResponseField name="updated_at" type="string">
  ISO-8601 timestamp of the latest status update, when available.
</ResponseField>

<ResponseField name="full_criteria_tree" type="object">
  Parsed criteria tree used to build the segment, when available.
</ResponseField>

<ResponseField name="error_criteria" type="object[]">
  Criteria that could not be processed, when applicable.
</ResponseField>

<ResponseField name="suggested_search" type="string">
  Suggested alternative query when the original search cannot be resolved.
</ResponseField>

<ResponseField name="total_count" type="integer">
  Exact completed segment size. `null` while unavailable.
</ResponseField>

<ResponseField name="estimated_billable_count" type="integer">
  Upper-bound count before PID deduplication. `null` while unavailable.
</ResponseField>

<ResponseField name="results_unlocked" type="boolean">
  Whether PIDs for the current materialization have been unlocked.
</ResponseField>

<ResponseField name="billable_count" type="integer">
  Exact net-new PIDs charged at unlock. `null` before unlock.
</ResponseField>

```json 200 — completed, locked theme={null}
{
  "segment_id": "8c2a6f71-3d41-4fc5-a2b6-1f53a5c81d77",
  "status": "completed",
  "updated_at": "2026-07-21T20:01:36.000000Z",
  "full_criteria_tree": {
    "node_type": "CRITERIA",
    "criteria": "Software engineers in Austin",
    "node_status": "FULL"
  },
  "error_criteria": null,
  "suggested_search": null,
  "total_count": 1284,
  "estimated_billable_count": 1284,
  "results_unlocked": false,
  "billable_count": null
}
```

```json 200 — unlocked theme={null}
{
  "segment_id": "8c2a6f71-3d41-4fc5-a2b6-1f53a5c81d77",
  "status": "completed",
  "updated_at": "2026-07-21T20:01:36.000000Z",
  "full_criteria_tree": {
    "node_type": "CRITERIA",
    "criteria": "Software engineers in Austin",
    "node_status": "FULL"
  },
  "error_criteria": null,
  "suggested_search": null,
  "total_count": 1284,
  "estimated_billable_count": 1284,
  "results_unlocked": true,
  "billable_count": 1207
}
```

## Errors

| Status | When                                                                              |
| ------ | --------------------------------------------------------------------------------- |
| `401`  | Missing/invalid credentials, or the API key has no associated user                |
| `404`  | Unknown `segment_id`, deleted segment, or segment belongs to another organization |
| `422`  | `segment_id` is not a valid UUID                                                  |
| `503`  | The segment status service is temporarily unavailable                             |

## Related

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