curl --request GET \
--url 'https://api.minerva.io/person-search/v0/search/550e8400-e29b-41d4-a716-446655440000' \
--header 'x-api-key: <api-key>'
{
"search_id": "550e8400-e29b-41d4-a716-446655440000",
"query": "Software engineers in Denver with a professional email on file",
"results": [
"p-a1b2c3d4e5f6",
"p-b2c3d4e5f6a7",
"p-c3d4e5f6a7b8"
],
"total_count": 1284,
"result_count": 3,
"total_contact_coverage": {
"personal_email": { "count": 812, "percent": 63.24 },
"professional_email": { "count": 1284, "percent": 100.0 },
"phone": { "count": 497, "percent": 38.71 },
"linkedin": { "count": 1110, "percent": 86.45 }
},
"results_contact_coverage": {
"personal_email": { "count": 2, "percent": 66.67 },
"professional_email": { "count": 3, "percent": 100.0 },
"phone": { "count": 1, "percent": 33.33 },
"linkedin": { "count": 3, "percent": 100.0 }
},
"created_at": "2026-04-24T15:02:11.482915+00:00"
}
{
"code": "unauthorized",
"message": "Unauthorized",
"api_request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
{
"code": "forbidden",
"message": "Not authorized for this route or plan",
"api_request_id": "b2c3d4e5-f6a7-1234-bcde-f12345678901"
}
{
"code": "not_found",
"message": "Search not found.",
"api_request_id": "c3d4e5f6-a7b8-2345-cdef-123456789012"
}
{
"code": "validation_error",
"message": "Invalid request data",
"api_request_id": "d4e5f6a7-b8c9-3456-def0-234567890123",
"details": [
{
"loc": ["search_id"],
"type": "uuid_parsing"
}
]
}
{
"code": "rate_limit_reached",
"message": "You reached your total request-rate limit, please contact help@minerva.io for help",
"api_request_id": "e5f6a7b8-c9d0-4567-ef01-345678901234"
}
Person Search
Get Person Search
Retrieve a previously created person search by id, returning the same payload as the original search
GET
/
person-search
/
v0
/
search
/
{search_id}
curl --request GET \
--url 'https://api.minerva.io/person-search/v0/search/550e8400-e29b-41d4-a716-446655440000' \
--header 'x-api-key: <api-key>'
{
"search_id": "550e8400-e29b-41d4-a716-446655440000",
"query": "Software engineers in Denver with a professional email on file",
"results": [
"p-a1b2c3d4e5f6",
"p-b2c3d4e5f6a7",
"p-c3d4e5f6a7b8"
],
"total_count": 1284,
"result_count": 3,
"total_contact_coverage": {
"personal_email": { "count": 812, "percent": 63.24 },
"professional_email": { "count": 1284, "percent": 100.0 },
"phone": { "count": 497, "percent": 38.71 },
"linkedin": { "count": 1110, "percent": 86.45 }
},
"results_contact_coverage": {
"personal_email": { "count": 2, "percent": 66.67 },
"professional_email": { "count": 3, "percent": 100.0 },
"phone": { "count": 1, "percent": 33.33 },
"linkedin": { "count": 3, "percent": 100.0 }
},
"created_at": "2026-04-24T15:02:11.482915+00:00"
}
{
"code": "unauthorized",
"message": "Unauthorized",
"api_request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
{
"code": "forbidden",
"message": "Not authorized for this route or plan",
"api_request_id": "b2c3d4e5-f6a7-1234-bcde-f12345678901"
}
{
"code": "not_found",
"message": "Search not found.",
"api_request_id": "c3d4e5f6-a7b8-2345-cdef-123456789012"
}
{
"code": "validation_error",
"message": "Invalid request data",
"api_request_id": "d4e5f6a7-b8c9-3456-def0-234567890123",
"details": [
{
"loc": ["search_id"],
"type": "uuid_parsing"
}
]
}
{
"code": "rate_limit_reached",
"message": "You reached your total request-rate limit, please contact help@minerva.io for help",
"api_request_id": "e5f6a7b8-c9d0-4567-ef01-345678901234"
}
Quick Answer
How do I re-fetch the results of a previous person search? Use this endpoint with thesearch_id you received from Person Search to get back the same search payload — PIDs, total count, and contact-channel coverage — without re-running the query.Common questions this endpoint answers:- How do I look up a saved person search?
- How do I re-download results from a search I ran earlier?
- How do I verify what query a given
search_idcorresponds to?
search_id returned from a previous POST /person-search/v0/search call.What you get back: The same PersonSearchResponse shape as the original search, including results, total_count, and both full-set and page-level contact coverage stats.Overview
The Get Person Search endpoint returns the stored payload for a search you created earlier with Person Search. The response shape is identical toPOST /person-search/v0/search, so you can use the same result-handling code for both endpoints.
Only searches that belong to your organization can be accessed. Requests for search_id values from a different organization return 404.
curl --request GET \
--url 'https://api.minerva.io/person-search/v0/search/550e8400-e29b-41d4-a716-446655440000' \
--header 'x-api-key: <api-key>'
Request
Headers
string
required
Your API key for authentication.
Path Parameters
string
required
UUID of the search to retrieve. This is the
search_id returned from POST /person-search/v0/search.Request Notes
- There is no request body and no query parameters.
- The search must belong to the organization associated with your API key.
Response
Success Response
The endpoint returns the same payload shape as Person Search. See that page for the full field reference ontotal_contact_coverage and results_contact_coverage.
string
UUID identifying the search. Matches the
search_id you requested.string
The normalized natural-language query associated with this search.
string[]
Array of Minerva PIDs previously returned for this search. Each PID has the format
p-{hash}.integer
Total number of people matching the search at the time it was run.
integer
Number of PIDs in
results.object
Availability of contact channels across the full match set of
total_count people. See the Person Search page for the field-level shape.object
Availability of contact channels across the PIDs in
results. Same shape as total_contact_coverage.string
ISO 8601 timestamp (UTC) indicating when the search was originally created.
{
"search_id": "550e8400-e29b-41d4-a716-446655440000",
"query": "Software engineers in Denver with a professional email on file",
"results": [
"p-a1b2c3d4e5f6",
"p-b2c3d4e5f6a7",
"p-c3d4e5f6a7b8"
],
"total_count": 1284,
"result_count": 3,
"total_contact_coverage": {
"personal_email": { "count": 812, "percent": 63.24 },
"professional_email": { "count": 1284, "percent": 100.0 },
"phone": { "count": 497, "percent": 38.71 },
"linkedin": { "count": 1110, "percent": 86.45 }
},
"results_contact_coverage": {
"personal_email": { "count": 2, "percent": 66.67 },
"professional_email": { "count": 3, "percent": 100.0 },
"phone": { "count": 1, "percent": 33.33 },
"linkedin": { "count": 3, "percent": 100.0 }
},
"created_at": "2026-04-24T15:02:11.482915+00:00"
}
{
"code": "unauthorized",
"message": "Unauthorized",
"api_request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
{
"code": "forbidden",
"message": "Not authorized for this route or plan",
"api_request_id": "b2c3d4e5-f6a7-1234-bcde-f12345678901"
}
{
"code": "not_found",
"message": "Search not found.",
"api_request_id": "c3d4e5f6-a7b8-2345-cdef-123456789012"
}
{
"code": "validation_error",
"message": "Invalid request data",
"api_request_id": "d4e5f6a7-b8c9-3456-def0-234567890123",
"details": [
{
"loc": ["search_id"],
"type": "uuid_parsing"
}
]
}
{
"code": "rate_limit_reached",
"message": "You reached your total request-rate limit, please contact help@minerva.io for help",
"api_request_id": "e5f6a7b8-c9d0-4567-ef01-345678901234"
}
Error Responses
Common Errors
401- Unauthorized: Invalid or missing API key403- Forbidden: The API key is valid but not authorized for this route or your plan tier404- Not Found: No search with the providedsearch_idexists for your organization. This is also returned if the search belongs to a different organization.422- Unprocessable Entity:search_idis not a valid UUID429- Too Many Requests: Rate limit or plan quota exceeded500- Internal Server Error: Unexpected server error
Error Example
Search not found:{
"code": "not_found",
"message": "Search not found.",
"api_request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
Implementation Notes
- Immutable payload: The stored payload reflects the results at the time the search was originally run. Re-fetching does not re-execute the query, so it will not reflect any new matches that have entered the dataset since.
- Organization scoping: A search is only accessible to the organization that created it. Cross-org access returns
404. - Retries: Safe to call repeatedly; the endpoint is idempotent.
Related Endpoints
- Person Search - Create a new person search
- Person Search Usage - Daily delivery limits and consumption history
- Contact Append - Async ABM contact jobs
- Enrich v2 - Fetch full profile data for the Minerva PIDs returned here
Was this page helpful?