Async Person Search Results

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>'

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>'

{
  "segment_id": "<string>",
  "pids": [
    "<string>"
  ],
  "total": 123,
  "returned": 123,
  "limit": 123,
  "offset": 123,
  "billable_count": 123,
  "unlocked_at": "<string>"
}

POST

person-search

search-jobs

{segment_id}

results

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>'

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>'

{
  "segment_id": "<string>",
  "pids": [
    "<string>"
  ],
  "total": 123,
  "returned": 123,
  "limit": 123,
  "offset": 123,
  "billable_count": 123,
  "unlocked_at": "<string>"
}

Overview

Async person-search PIDs remain locked until you explicitly unlock the completed segment. This endpoint requires a full materialization; the default preview mode reports count and statistics but does not create the full PID artifact required here. This page documents step 3 of the flow in isolation. For the whole flow with worked examples, see the Async Person Search walkthrough.

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 full materialization completes, or for a preview-only job, 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.

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.

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.

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"]

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>'

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>'

Request

Headers

string

required

An API key for the organization that submitted the search.

Path Parameters

string

required

UUID of a completed async person search owned by your organization.

Query Parameters

integer

Number of PIDs to return. Defaults to 100. Range: 1–100.

integer

Number of PIDs to skip. Defaults to 0; minimum is 0.

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.

string

Async search and segment UUID.

string[]

PID page for the requested limit and offset. Contains at most 100 items.

integer

Total PIDs in the completed segment.

integer

Number of PIDs in this response.

integer

Echo of the requested page size.

integer

Echo of the requested offset.

integer

Exact net-new PID count charged by the unlock. Remains stable on later pages.

string

ISO-8601 timestamp when this materialization was unlocked.

200

{
  "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 or invalid credentials
`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`	Job is preview-only, full materialization 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

⌘I

Getting Started

Core Endpoints

Validation Workflows

Person Search

Usage

Storage

Segments

Quick Answer

Overview

Billing behavior

Request

Headers

Path Parameters

Query Parameters

Response

Success Response (`200 OK`)

Errors

​Quick Answer

​Overview

​Billing behavior

​Pagination

​Request

​Headers

​Path Parameters

​Query Parameters

​Response

​Success Response (200 OK)

​Errors

​Related

Quick Answer

Overview

Billing behavior

Pagination

Request

Headers

Path Parameters

Query Parameters

Response

Success Response (`200 OK`)

Errors

Related