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>",
  "error": {},
  "error.code": "<string>",
  "error.message": "<string>",
  "error.retryable": true,
  "materialization_extent": "<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,
  "stats": {}
}

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>",
  "error": {},
  "error.code": "<string>",
  "error.message": "<string>",
  "error.retryable": true,
  "materialization_extent": "<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,
  "stats": {}
}

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. This page documents step 2 of the flow in isolation. For the whole flow with worked examples, see the Async Person Search walkthrough.

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`	Preview materialization is complete

Count and billing fields

total_count is the audience match count once preview or full processing completes. 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 a full materialization is successfully unlocked. Preview jobs cannot use the public results endpoint.

Billing and results unlock apply only to full materialization. The estimate covers the entire segment, not one results page.

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

string

required

An API key for the organization that submitted the search.

Path Parameters

string

required

UUID returned by Async Person Search.

Response

Success Response (`200 OK`)

string

Async search and segment UUID.

string

Current processing status.

object

Terminal failure details for failed or cancelled jobs. null for every other status.

string

Stable machine-readable failure category: search_criteria_failed, search_processing_failed, or search_cancelled.

string

Caller-safe explanation and, when available, a suggested replacement search.

boolean

Always false. Failed and cancelled jobs are terminal; submit a new or revised search to continue.

string

Effective materialization mode applied to this job: preview or full. Use this field—not the terminal status—to determine whether the public results endpoint is available.

string

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

object

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

object[]

Criteria that could not be processed, when applicable.

string

Suggested alternative query when the original search cannot be resolved.

integer

Audience match count after preview or full processing. null while unavailable.

integer

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

boolean

Whether PIDs for the current materialization have been unlocked.

integer

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

object

Compact contact coverage and demographic distributions for the preview or completed segment. null while the job is still processing or when it fails.

Completed-job statistics

Every distribution bucket uses { label, count, percentage }. Percentages use total_count as the denominator and are rounded to two decimal places.

age uses Under 18, 18-24, ten-year adult bands through 65-74, and 75+.
gender uses Female, Male, and Unknown.
home_ownership uses Owned, Rented, and Unknown.
job_title is a high-cardinality dimension. It returns only the ten most frequent standardized current titles; remaining titles are intentionally omitted and are not combined into an Other bucket.
current_address_state returns the ten largest buckets plus an Other bucket when more values are present.
Statistics do not unlock results or incur PID billing.

200 — completed, locked

{
  "segment_id": "8c2a6f71-3d41-4fc5-a2b6-1f53a5c81d77",
  "status": "completed",
  "error": null,
  "materialization_extent": "preview",
  "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,
  "stats": {
    "coverage": {
      "email": { "count": 1012, "percentage": 78.82 },
      "phone": { "count": 744, "percentage": 57.94 },
      "address": { "count": 1198, "percentage": 93.3 }
    },
    "distributions": {
      "age": [
        { "label": "25-34", "count": 410, "percentage": 31.93 }
      ],
      "gender": [
        { "label": "Female", "count": 604, "percentage": 47.04 }
      ],
      "education_level": [],
      "job_title": [],
      "home_ownership": [],
      "income": [],
      "wealth": [],
      "current_address_state": []
    }
  }
}

200 — unlocked

{
  "segment_id": "8c2a6f71-3d41-4fc5-a2b6-1f53a5c81d77",
  "status": "completed",
  "error": null,
  "materialization_extent": "full",
  "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,
  "stats": {
    "coverage": {
      "email": { "count": 1012, "percentage": 78.82 },
      "phone": { "count": 744, "percentage": 57.94 },
      "address": { "count": 1198, "percentage": 93.3 }
    },
    "distributions": {
      "age": [
        { "label": "25-34", "count": 410, "percentage": 31.93 }
      ],
      "gender": [
        { "label": "Female", "count": 604, "percentage": 47.04 }
      ],
      "education_level": [],
      "job_title": [],
      "home_ownership": [],
      "income": [],
      "wealth": [],
      "current_address_state": []
    }
  }
}

200 — failed criteria

{
  "segment_id": "8c2a6f71-3d41-4fc5-a2b6-1f53a5c81d77",
  "status": "failed",
  "error": {
    "code": "search_criteria_failed",
    "message": "Person Search could not resolve the audience using supported criteria. Suggested search: Aerospace executives in the United States",
    "retryable": false
  },
  "materialization_extent": "preview",
  "updated_at": "2026-07-21T20:01:36.000000Z",
  "full_criteria_tree": null,
  "error_criteria": [
    { "criteria": "People who own a moon base" }
  ],
  "suggested_search": "Aerospace executives in the United States",
  "total_count": null,
  "estimated_billable_count": null,
  "results_unlocked": false,
  "billable_count": null,
  "stats": null
}

Errors

Status	When
`401`	Missing or invalid credentials
`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

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`)

Completed-job statistics

Errors

​Quick Answer

​Overview

​Status values

​Count and billing fields

​Request

​Headers

​Path Parameters

​Response

​Success Response (200 OK)

​Completed-job statistics

​Errors

​Related

Quick Answer

Overview

Status values

Count and billing fields

Request

Headers

Path Parameters

Response

Success Response (`200 OK`)

Completed-job statistics

Errors

Related