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

> Unlock a completed person-search segment, bill its net-new PIDs once, and page PID results

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

  **How do I retrieve async person-search results?** After status is `completed`,
  call `POST` on this path once to unlock the entire segment and return a PID
  page. Use `GET` on the same path for later pages without re-billing.

  **Maximum page size:** `100` PIDs.
</div>

## Overview

Async person-search PIDs remain locked until you explicitly unlock the
completed segment.

| Method             | Purpose                                                               | Bills?    |
| ------------------ | --------------------------------------------------------------------- | --------- |
| `POST .../results` | Unlock the full current materialization and return the requested page | Yes, once |
| `GET .../results`  | Return a page after unlock                                            | No        |

If you call `GET` before unlocking, the API returns `409 Conflict`. If you call
`POST` before materialization completes, it also returns `409 Conflict`.

### Billing behavior

The first successful `POST` unlock considers **every PID in the completed
segment**, regardless of the requested `limit` and `offset`.

* Billing uses the `platform_records_under_management` metric.
* Only net-new PIDs for your organization in the current billing year are
  charged; previously unlocked PIDs are deduplicated.
* `estimated_billable_count` on the status endpoint is the full segment size
  before deduplication.
* `billable_count` in this response is the exact number charged.
* Unlock is idempotent. Repeating `POST` or paging with `GET` does not charge
  the same materialization again.
* If credits are insufficient, the unlock fails with `402` and no PID page is
  returned.

<Warning>
  `limit` controls only how many PIDs are returned in this response. For
  example, unlocking a 50,000-PID segment with `limit=10` still considers all
  50,000 PIDs for deduplicated billing.
</Warning>

### Pagination

Each response returns at most `100` PIDs. Start with `offset=0`, then increase
the offset by the number returned until `offset + returned >= total`.
The 100-PID limit applies only to each HTTP response, not to the materialized
segment; `total` reports the full result count.

```python theme={null}
import requests

base_url = "https://api.minerva.io"
segment_id = "8c2a6f71-3d41-4fc5-a2b6-1f53a5c81d77"
headers = {"x-api-key": "<api-key>"}

# Unlock once and receive the first page.
response = requests.post(
    f"{base_url}/person-search/v0/search-jobs/{segment_id}/results",
    headers=headers,
    params={"limit": 100, "offset": 0},
)
response.raise_for_status()
page = response.json()
pids = list(page["pids"])

# Subsequent pages are side-effect-free GET requests.
offset = page["returned"]
while offset < page["total"]:
    response = requests.get(
        f"{base_url}/person-search/v0/search-jobs/{segment_id}/results",
        headers=headers,
        params={"limit": 100, "offset": offset},
    )
    response.raise_for_status()
    page = response.json()
    pids.extend(page["pids"])
    offset += page["returned"]
```

<RequestExample>
  ```bash Unlock and get first page (POST) theme={null}
  curl --request POST \
    --url 'https://api.minerva.io/person-search/v0/search-jobs/8c2a6f71-3d41-4fc5-a2b6-1f53a5c81d77/results?limit=100&offset=0' \
    --header 'x-api-key: <api-key>'
  ```

  ```bash Get next page (GET) theme={null}
  curl --request GET \
    --url 'https://api.minerva.io/person-search/v0/search-jobs/8c2a6f71-3d41-4fc5-a2b6-1f53a5c81d77/results?limit=100&offset=100' \
    --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 of a completed async person search owned by your organization.
</ParamField>

### Query Parameters

<ParamField query="limit" type="integer">
  Number of PIDs to return. Defaults to `100`. Range: `1`–`100`.
</ParamField>

<ParamField query="offset" type="integer">
  Number of PIDs to skip. Defaults to `0`; minimum is `0`.
</ParamField>

## Response

### Success Response (`200 OK`)

`POST` and `GET` return the same shape. Results contain Minerva PIDs only; use
an enrichment endpoint separately if you need person attributes.

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

<ResponseField name="pids" type="string[]">
  PID page for the requested `limit` and `offset`. Contains at most `100` items.
</ResponseField>

<ResponseField name="total" type="integer">
  Total PIDs in the completed segment.
</ResponseField>

<ResponseField name="returned" type="integer">
  Number of PIDs in this response.
</ResponseField>

<ResponseField name="limit" type="integer">
  Echo of the requested page size.
</ResponseField>

<ResponseField name="offset" type="integer">
  Echo of the requested offset.
</ResponseField>

<ResponseField name="billable_count" type="integer">
  Exact net-new PID count charged by the unlock. Remains stable on later pages.
</ResponseField>

<ResponseField name="unlocked_at" type="string">
  ISO-8601 timestamp when this materialization was unlocked.
</ResponseField>

```json 200 theme={null}
{
  "segment_id": "8c2a6f71-3d41-4fc5-a2b6-1f53a5c81d77",
  "pids": [
    "p-a1b2c3d4e5f6",
    "p-b2c3d4e5f6a7",
    "p-c3d4e5f6a7b8"
  ],
  "total": 1284,
  "returned": 3,
  "limit": 100,
  "offset": 0,
  "billable_count": 1207,
  "unlocked_at": "2026-07-21T20:02:10.000000Z"
}
```

## Errors

| Status | When                                                                                                                        |
| ------ | --------------------------------------------------------------------------------------------------------------------------- |
| `401`  | Missing/invalid credentials, or the API key has no associated user                                                          |
| `402`  | Insufficient credits to unlock the segment's net-new PIDs                                                                   |
| `404`  | Unknown segment, deleted segment, segment belongs to another organization, or it is not a third-party person-search segment |
| `409`  | Segment is incomplete, unlock is in progress, or `GET` was called before unlock                                             |
| `422`  | Invalid UUID, `limit`, or `offset`                                                                                          |
| `503`  | Billing or segment result delivery is temporarily unavailable                                                               |

## Related

* [Async Person Search](/api-reference/person-search-job-submit)
* [Async Person Search Status](/api-reference/person-search-job-status)
* [Enrich v2](/api-reference/enrich-v2)