Async Person Search Status

curl --request GET \
  --url 'https://api.minerva.io/person-search/v0/search-jobs/8c2a6f71-3d41-4fc5-a2b6-1f53a5c81d77' \
  --header 'x-api-key: <api-key>'

{
  "segment_id": "<string>",
  "status": "<string>",
  "updated_at": "<string>",
  "full_criteria_tree": {},
  "error_criteria": [
    {}
  ],
  "suggested_search": "<string>",
  "total_count": 123,
  "estimated_billable_count": 123,
  "results_unlocked": true,
  "billable_count": 123
}

GET

person-search

search-jobs

{segment_id}

curl --request GET \
  --url 'https://api.minerva.io/person-search/v0/search-jobs/8c2a6f71-3d41-4fc5-a2b6-1f53a5c81d77' \
  --header 'x-api-key: <api-key>'

{
  "segment_id": "<string>",
  "status": "<string>",
  "updated_at": "<string>",
  "full_criteria_tree": {},
  "error_criteria": [
    {}
  ],
  "suggested_search": "<string>",
  "total_count": 123,
  "estimated_billable_count": 123,
  "results_unlocked": true,
  "billable_count": 123
}

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.

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.

curl --request GET \
  --url 'https://api.minerva.io/person-search/v0/search-jobs/8c2a6f71-3d41-4fc5-a2b6-1f53a5c81d77' \
  --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 returned by Async Person Search.

Response

Success Response (`200 OK`)

segment_id

string

Async search and segment UUID.

status

string

Current processing status.

updated_at

string

ISO-8601 timestamp of the latest status update, when available.

full_criteria_tree

object

Parsed criteria tree used to build the segment, when available.

error_criteria

object[]

Criteria that could not be processed, when applicable.

suggested_search

string

Suggested alternative query when the original search cannot be resolved.

total_count

integer

Exact completed segment size. null while unavailable.

estimated_billable_count

integer

Upper-bound count before PID deduplication. null while unavailable.

results_unlocked

boolean

Whether PIDs for the current materialization have been unlocked.

billable_count

integer

Exact net-new PIDs charged at unlock. null before unlock.

200 — completed, locked

{
  "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
}

200 — unlocked

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

Async Person Search Async Person Search Results

⌘I

Getting Started

Core Endpoints

Validation Workflows

Person Search

Usage

Storage

Segments

Quick Answer

Overview

Status values

Count and billing fields

Request

Headers

Path Parameters

Response

Success Response (`200 OK`)

Errors

​Quick Answer

​Overview

​Status values

​Count and billing fields

​Request

​Headers

​Path Parameters

​Response

​Success Response (200 OK)

​Errors

​Related

Quick Answer

Overview

Status values

Count and billing fields

Request

Headers

Path Parameters

Response

Success Response (`200 OK`)

Errors

Related