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.

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.

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

x-api-key

string

required

The user-associated API key that submitted the search.

Path Parameters

segment_id

string

required

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

Query Parameters

limit

integer

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

offset

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.

segment_id

string

Async search and segment UUID.

pids

string[]

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

total

integer

Total PIDs in the completed segment.

returned

integer

Number of PIDs in this response.

limit

integer

Echo of the requested page size.

offset

integer

Echo of the requested offset.

billable_count

integer

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

unlocked_at

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

Async Person Search Status Person Search Usage

⌘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