> ## Documentation Index
> Fetch the complete documentation index at: https://docs.minerva.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Person Search Usage

> Retrieve your organization's daily person-search delivery limits, current-day consumption, and recent per-day history

<div style={{ display: 'none' }} aria-hidden="false">
  ## 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.
</div>

## 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

<RequestExample>
  ```bash Request Example theme={null}
  curl --request GET \
    --url 'https://api.minerva.io/person-search/v0/usage?days=30' \
    --header 'x-api-key: <api-key>'
  ```
</RequestExample>

## Request

### Headers

<ParamField header="x-api-key" type="string" required>
  Your API key for authentication.
</ParamField>

### Query Parameters

<ParamField query="days" type="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`.
</ParamField>

### 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

<ResponseField name="org_id" type="string">
  UUID of the organization associated with your API key.
</ResponseField>

<ResponseField name="daily_record_limit" type="integer">
  Maximum number of person records that can be delivered per UTC day for your organization.
</ResponseField>

<ResponseField name="current_day_records_delivered" type="integer">
  Records delivered so far today (UTC day). Counts toward `daily_record_limit`.
</ResponseField>

<ResponseField name="current_day_remaining" type="integer">
  Remaining record budget for today, computed as `max(0, daily_record_limit - current_day_records_delivered)`.
</ResponseField>

<ResponseField name="history" type="array">
  Array of `DailyUsage` objects, one per UTC calendar day in the requested window. See [Daily usage object](#daily-usage-object) below.
</ResponseField>

### Daily usage object

<ResponseField name="period_start" type="string">
  UTC calendar date for this row, in `YYYY-MM-DD` format.
</ResponseField>

<ResponseField name="records_delivered" type="integer">
  Number of person records delivered by the person search API on that day.
</ResponseField>

<ResponseField name="searches_created" type="integer">
  Number of `POST /person-search/v0/search` calls that produced a stored search on that day.
</ResponseField>

<ResponseField name="parse_requests" type="integer">
  Natural-language query parse requests processed on that day.
</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "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
      }
    ]
  }
  ```

  ```json 401 theme={null}
  {
    "code": "unauthorized",
    "message": "Unauthorized",
    "api_request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
  ```

  ```json 403 theme={null}
  {
    "code": "forbidden",
    "message": "Not authorized for this route or plan",
    "api_request_id": "b2c3d4e5-f6a7-1234-bcde-f12345678901"
  }
  ```

  ```json 422 theme={null}
  {
    "code": "validation_error",
    "message": "Invalid request data",
    "api_request_id": "c3d4e5f6-a7b8-2345-cdef-123456789012",
    "details": [
      {
        "loc": ["days"],
        "type": "less_than_equal"
      }
    ]
  }
  ```

  ```json 429 theme={null}
  {
    "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"
  }
  ```
</ResponseExample>

## 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`:**

```json theme={null}
{
  "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:**

```python theme={null}
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:**

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

## Related Endpoints

* [Person Search](/api-reference/person-search) - Create a new person search
* [Get Person Search](/api-reference/person-search-get) - Retrieve a previously created search by id
* [Endpoint Usage](/api-reference/usage-endpoints) - Org-wide usage metrics across other Minerva endpoints