Person Search Usage

curl --request GET \
  --url 'https://api.minerva.io/person-search/v0/usage?days=30' \
  --header 'x-api-key: <api-key>'

{
  "org_id": "8e3c4b7a-2d31-4f48-9b5a-1c2d3e4f5a6b",
  "daily_record_limit": 1000000,
  "current_day_records_delivered": 12840,
  "current_day_remaining": 987160,
  "history": [
    {
      "period_start": "2026-04-24",
      "records_delivered": 12840,
      "searches_created": 9,
      "parse_requests": 11
    },
    {
      "period_start": "2026-04-23",
      "records_delivered": 45210,
      "searches_created": 22,
      "parse_requests": 27
    },
    {
      "period_start": "2026-04-22",
      "records_delivered": 0,
      "searches_created": 0,
      "parse_requests": 0
    }
  ]
}

{
  "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": "validation_error",
  "message": "Invalid request data",
  "api_request_id": "c3d4e5f6-a7b8-2345-cdef-123456789012",
  "details": [
    {
      "loc": ["days"],
      "type": "less_than_equal"
    }
  ]
}

{
  "code": "rate_limit_reached",
  "message": "You reached your total request-rate limit, please contact help@minerva.io for help",
  "api_request_id": "d4e5f6a7-b8c9-3456-def0-234567890123"
}

GET

person-search

usage

curl --request GET \
  --url 'https://api.minerva.io/person-search/v0/usage?days=30' \
  --header 'x-api-key: <api-key>'

{
  "org_id": "8e3c4b7a-2d31-4f48-9b5a-1c2d3e4f5a6b",
  "daily_record_limit": 1000000,
  "current_day_records_delivered": 12840,
  "current_day_remaining": 987160,
  "history": [
    {
      "period_start": "2026-04-24",
      "records_delivered": 12840,
      "searches_created": 9,
      "parse_requests": 11
    },
    {
      "period_start": "2026-04-23",
      "records_delivered": 45210,
      "searches_created": 22,
      "parse_requests": 27
    },
    {
      "period_start": "2026-04-22",
      "records_delivered": 0,
      "searches_created": 0,
      "parse_requests": 0
    }
  ]
}

{
  "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": "validation_error",
  "message": "Invalid request data",
  "api_request_id": "c3d4e5f6-a7b8-2345-cdef-123456789012",
  "details": [
    {
      "loc": ["days"],
      "type": "less_than_equal"
    }
  ]
}

{
  "code": "rate_limit_reached",
  "message": "You reached your total request-rate limit, please contact help@minerva.io for help",
  "api_request_id": "d4e5f6a7-b8c9-3456-def0-234567890123"
}

Overview

The Person Search Usage endpoint returns quota and consumption metrics scoped to the organization associated with your API key. Use it to:

Check today’s remaining record budget before issuing additional searches
Power a usage dashboard or chart day-over-day trends
Reconcile internal billing records against delivered record counts

Each row of history represents a single UTC calendar day, with counts for:

records_delivered - PIDs delivered in search responses
searches_created - number of POST /person-search/v0/search calls that produced a stored search
parse_requests - natural-language query parses performed for searches

curl --request GET \
  --url 'https://api.minerva.io/person-search/v0/usage?days=30' \
  --header 'x-api-key: <api-key>'

Request

Headers

string

required

Your API key for authentication.

Query Parameters

integer

default:"30"

Number of UTC calendar days of history to include, counting back from today (inclusive). Must be between 1 and 90. Defaults to 30.

Request Notes

There is no request body.
The date range is always anchored to today (UTC) and cannot be customized beyond days.

Response

Success Response

string

UUID of the organization associated with your API key.

integer

Maximum number of person records that can be delivered per UTC day for your organization.

integer

Records delivered so far today (UTC day). Counts toward daily_record_limit.

integer

Remaining record budget for today, computed as max(0, daily_record_limit - current_day_records_delivered).

array

Array of DailyUsage objects, one per UTC calendar day in the requested window. See Daily usage object below.

Daily usage object

string

UTC calendar date for this row, in YYYY-MM-DD format.

integer

Number of person records delivered by the person search API on that day.

integer

Number of POST /person-search/v0/search calls that produced a stored search on that day.

integer

Natural-language query parse requests processed on that day.

{
  "org_id": "8e3c4b7a-2d31-4f48-9b5a-1c2d3e4f5a6b",
  "daily_record_limit": 1000000,
  "current_day_records_delivered": 12840,
  "current_day_remaining": 987160,
  "history": [
    {
      "period_start": "2026-04-24",
      "records_delivered": 12840,
      "searches_created": 9,
      "parse_requests": 11
    },
    {
      "period_start": "2026-04-23",
      "records_delivered": 45210,
      "searches_created": 22,
      "parse_requests": 27
    },
    {
      "period_start": "2026-04-22",
      "records_delivered": 0,
      "searches_created": 0,
      "parse_requests": 0
    }
  ]
}

{
  "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": "validation_error",
  "message": "Invalid request data",
  "api_request_id": "c3d4e5f6-a7b8-2345-cdef-123456789012",
  "details": [
    {
      "loc": ["days"],
      "type": "less_than_equal"
    }
  ]
}

{
  "code": "rate_limit_reached",
  "message": "You reached your total request-rate limit, please contact help@minerva.io for help",
  "api_request_id": "d4e5f6a7-b8c9-3456-def0-234567890123"
}

Behavior Notes

Results are scoped to the organization associated with your API key.
All dates and day boundaries are in UTC.
current_day_records_delivered is the same value that appears in the history row whose period_start equals today’s UTC date.
Days with no activity are included in history with zeroed counters, so the array length is always equal to the requested days value.
current_day_remaining is clamped at zero; it never goes negative even if delivery briefly exceeds the daily limit.

Error Responses

Common Errors

401 - Unauthorized: Invalid or missing API key
403 - Forbidden: The API key is valid but not authorized for this route or your plan tier
422 - Unprocessable Entity: days is not an integer, or is outside the allowed range 1-90
429 - Too Many Requests: Rate limit or plan quota exceeded
500 - Internal Server Error: Unexpected server error

Error Example

Out-of-range days:

{
  "code": "validation_error",
  "message": "Invalid request data",
  "api_request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "details": [
    {
      "loc": ["days"],
      "type": "less_than_equal"
    }
  ]
}

Common Integration Patterns

Check remaining budget before a large search job:

usage = minerva_api.get("/person-search/v0/usage", params={"days": 1})
if usage["current_day_remaining"] < planned_record_count:
    raise RuntimeError("Not enough daily budget remaining for this job")

Build a day-over-day consumption chart:

usage = minerva_api.get("/person-search/v0/usage", params={"days": 30})
for row in usage["history"]:
    print(row["period_start"], row["records_delivered"])

Person Search - Create a new person search
Get Person Search - Retrieve a previously created search by id
Endpoint Usage - Org-wide usage metrics across other Minerva endpoints

3. Unlock & Page Results Contact Append

⌘I

Getting Started

Core Endpoints

Validation Workflows

Person Search

Usage

Storage

Segments

Quick Answer

Overview

Request

Headers

Query Parameters

Request Notes

Response

Success Response

Daily usage object

Behavior Notes

Error Responses

Common Errors

Error Example

Common Integration Patterns

​Quick Answer

​Overview

​Request

​Headers

​Query Parameters

​Request Notes

​Response

​Success Response

​Daily usage object

​Behavior Notes

​Error Responses

​Common Errors

​Error Example

​Common Integration Patterns

​Related Endpoints

Quick Answer

Overview

Request

Headers

Query Parameters

Request Notes

Response

Success Response

Daily usage object

Behavior Notes

Error Responses

Common Errors

Error Example

Common Integration Patterns

Related Endpoints