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>",
  "created_at": "<string>",
  "updated_at": "<string>",
  "full_criteria_tree": {},
  "error_criteria": [
    {}
  ],
  "suggested_search": "<string>",
  "total_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>",
  "created_at": "<string>",
  "updated_at": "<string>",
  "full_criteria_tree": {},
  "error_criteria": [
    {}
  ],
  "suggested_search": "<string>",
  "total_count": 123,
  "stats": {}
}

Poll every 2–5 seconds until the search reaches a terminal status. Once a full search is completed, page its PIDs. Polling and PID retrieval do not consume record capacity.

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
`counting`	Computing the exact audience count
`computing_stats`	Computing demographics and contact coverage; a preview count may already be available
`materializing`	Collecting and staging matching audience members
`exporting`	Writing audience result files
`finalizing`	Persisting the completed result
`querying`	Processing; a more specific worker phase is unavailable
`completed`	Requested preview or full materialization is complete
`failed`	Terminal processing failure
`cancelled`	Processing was cancelled
`previewed`	Preview materialization is complete

Preview jobs can return completed. Use materialization_extent to distinguish preview from full; status alone does not indicate that full PID results are available.

Progressive preview results

Submit once and poll the same job ID. For third-party previews that execute as one Elasticsearch query, total_count becomes available before demographic statistics finish. Use total_count !== null to display the audience size; 0 means the completed count found no matches. Continue polling for stats and terminal status.

Count available; demographics still running

{
  "segment_id": "8c2a6f71-3d41-4fc5-a2b6-1f53a5c81d77",
  "status": "computing_stats",
  "materialization_extent": "preview",
  "created_at": "2026-10-15T17:00:00Z",
  "total_count": 12843,
  "stats": null
}

total_count is exact for the count query, not a threshold or sampled estimate. Demographic statistics retain their existing sampling behavior for large audiences. If a later step fails, the count remains available alongside status: "failed"; a count alone does not mean the preview completed. Statuses reflect observed worker progress, so fast stages may be skipped between polls. Terminal status takes precedence over delayed worker updates. Clients should continue polling for any nonterminal status, including new processing stages. Full jobs and previews requiring other execution paths may only provide their count when processing completes.

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, search_timed_out, search_worker_lost, 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. Results are available when this is full and status is completed.

string

ISO-8601 submission timestamp.

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

Exact audience match count, available before demographics finish for supported third-party previews. null until available; retained if a later step fails.

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.

200 — completed preview

{
  "segment_id": "8c2a6f71-3d41-4fc5-a2b6-1f53a5c81d77",
  "status": "completed",
  "error": null,
  "materialization_extent": "preview",
  "created_at": "2026-07-21T20:00:00.000000Z",
  "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,
  "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",
  "created_at": "2026-07-21T20:00:00.000000Z",
  "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,
  "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

Processing deadlines

Processing limits depend on the deployed worker configuration. The legacy Lambda worker has a four-minute processing budget, excluding queue wait and startup. When that budget is exhausted, polling returns failed with error.code: "search_timed_out". When Temporal workers are enabled for the async API, full materializations may run longer than five minutes. Worker failure or an execution timeout is persisted as failed with error.code: "search_worker_lost". Failure reporting can be delayed while the status service is unavailable. querying and updated_at do not establish worker liveness: updated_at is a stored segment update timestamp, not a heartbeat. Stop polling on terminal statuses. If your own polling timeout expires, you can resume polling the same job later. For very large audiences, narrow the criteria or use materialization_extent: "preview" when you only need counts and statistics.

Async API worker liveness

Jobs submitted through the async API may include an optional worker object with status (queued, running, or finished) and heartbeat_at (an ISO 8601 timestamp or null). This reports worker liveness, not a completion estimate. Continue to use the job’s top-level terminal status and error to determine success or failure. A stale heartbeat alone does not prove failure. Full materializations may take longer than five minutes.

Getting Started

Core Endpoints

Validation Workflows

Person Search

Usage

Storage

Segments

Status values

Progressive preview results

Request

Headers

Path Parameters

Response

Success Response (`200 OK`)

Completed-job statistics

Errors

Processing deadlines

Async API worker liveness

​Status values

​Progressive preview results

​Request

​Headers

​Path Parameters

​Response

​Success Response (200 OK)

​Completed-job statistics

​Errors

​Related

​Processing deadlines

​Async API worker liveness

Status values

Progressive preview results

Request

Headers

Path Parameters

Response

Success Response (`200 OK`)

Completed-job statistics

Errors

Related

Processing deadlines

Async API worker liveness