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>"
}Async Person Search
Async Person Search Results
Unlock a completed person-search segment and page free PID-only results
POST
/
person-search
/
v0
/
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>"
}Quick Answer
How do I retrieve async person-search results? Submit the job withmaterialization_extent: "full". 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. PID-only results are free.Maximum page size: 100 PIDs.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 | No |
GET .../results | Return a page after unlock | No |
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
PID-only results do not consume record capacity.billable_count is 0.
Unlocking or paging these PIDs does not license the underlying full records.
Request full data with Enrich v2, or deliver it through
a full-record activation. Those delivery paths check the canonical Billing v2
ledger and count each delivered record once per organization per term, across
channels. A later term counts the delivered record again.
Pagination
Each response returns at most100 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
Always
0: PID-only results do not consume record capacity.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": 0,
"unlocked_at": "2026-07-21T20:02:10.000000Z"
}
Errors
| Status | When |
|---|---|
401 | Missing or invalid credentials |
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 |
Related
Was this page helpful?