Skip to main content
GET
/
person-search
/
v0
/
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
    }
  ]
}

​
Quick Answer

How do I see my person-search usage? Use this endpoint to check your organization’s daily record-delivery limit, how many records you’ve already been charged for today, how much of the daily budget is remaining, and a per-day history of search activity.Common questions this endpoint answers:
  • What’s my daily person-search record limit?
  • How many records have I been delivered today?
  • How much quota do I have left for today?
  • How many searches did we run per day over the last month?
  • How many natural-language parse requests did we consume per day?
What you get back: The org’s daily_record_limit, records delivered today, remaining budget today, and a per-UTC-day history array with delivered record counts, searches created, and parse requests.

​
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

​
x-api-key
string
required
Your API key for authentication.

​
Query Parameters

​
days
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

​
org_id
string
UUID of the organization associated with your API key.
​
daily_record_limit
integer
Maximum number of person records that can be delivered per UTC day for your organization.
​
current_day_records_delivered
integer
Records delivered so far today (UTC day). Counts toward daily_record_limit.
​
current_day_remaining
integer
Remaining record budget for today, computed as max(0, daily_record_limit - current_day_records_delivered).
​
history
array
Array of DailyUsage objects, one per UTC calendar day in the requested window. See Daily usage object below.

​
Daily usage object

​
period_start
string
UTC calendar date for this row, in YYYY-MM-DD format.
​
records_delivered
integer
Number of person records delivered by the person search API on that day.
​
searches_created
integer
Number of POST /person-search/v0/search calls that produced a stored search on that day.
​
parse_requests
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
    }
  ]
}

​
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
  • 422 - Unprocessable Entity: days is not an integer, or is outside the allowed range 1-90
  • 500 - Internal Server Error: Unexpected server error

​
Error Example

Out-of-range days: 
{
  "error": {
    "code": "validation_error",
    "message": "Input should be less than or equal to 90"
  }
}

​
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"])