Endpoint Usage

curl --request GET \
  --url 'https://api.minerva.io/usage' \
  --header 'x-api-key: <api-key>' \
  --get \
  --data-urlencode 'start_date=2026-03-01' \
  --data-urlencode 'end_date=2026-03-26' \
  --data-urlencode 'bucketing_size=day' \
  --data-urlencode 'timezone=UTC' \
  --data-urlencode 'include_unused_endpoints=false'

{
  "api_request_id": "req_usage_12345",
  "results": [
    {
      "endpoint": "v1/resolve",
      "total_requests": 42,
      "num_input_records": 1200,
      "num_resolvable_records": 1100,
      "num_matches": 980,
      "last_requested_at": "2026-03-26T14:00:00+00:00",
      "buckets": [
        {
          "bucket_start": "2026-03-24T00:00:00+00:00",
          "total_requests": 10,
          "num_input_records": 300,
          "num_resolvable_records": 280,
          "num_matches": 250
        },
        {
          "bucket_start": "2026-03-25T00:00:00+00:00",
          "total_requests": 12,
          "num_input_records": 350,
          "num_resolvable_records": 320,
          "num_matches": 285
        },
        {
          "bucket_start": "2026-03-26T00:00:00+00:00",
          "total_requests": 20,
          "num_input_records": 550,
          "num_resolvable_records": 500,
          "num_matches": 445
        }
      ],
      "overall_match_rate": 0.8166666666666667,
      "resolvable_match_rate": 0.8909090909090909
    },
    {
      "endpoint": "v2/enrich",
      "total_requests": 8,
      "num_input_records": 150,
      "num_resolvable_records": 150,
      "num_matches": 150,
      "last_requested_at": "2026-03-25T09:30:00+00:00",
      "buckets": [
        {
          "bucket_start": "2026-03-24T00:00:00+00:00",
          "total_requests": 2,
          "num_input_records": 40,
          "num_resolvable_records": 40,
          "num_matches": 40
        },
        {
          "bucket_start": "2026-03-25T00:00:00+00:00",
          "total_requests": 6,
          "num_input_records": 110,
          "num_resolvable_records": 110,
          "num_matches": 110
        },
        {
          "bucket_start": "2026-03-26T00:00:00+00:00",
          "total_requests": 0,
          "num_input_records": 0,
          "num_resolvable_records": 0,
          "num_matches": 0
        }
      ],
      "overall_match_rate": 1.0,
      "resolvable_match_rate": 1.0
    }
  ],
  "request_completed_at": "2026-03-26T14:05:12.123456Z"
}

GET

usage

curl --request GET \
  --url 'https://api.minerva.io/usage' \
  --header 'x-api-key: <api-key>' \
  --get \
  --data-urlencode 'start_date=2026-03-01' \
  --data-urlencode 'end_date=2026-03-26' \
  --data-urlencode 'bucketing_size=day' \
  --data-urlencode 'timezone=UTC' \
  --data-urlencode 'include_unused_endpoints=false'

{
  "api_request_id": "req_usage_12345",
  "results": [
    {
      "endpoint": "v1/resolve",
      "total_requests": 42,
      "num_input_records": 1200,
      "num_resolvable_records": 1100,
      "num_matches": 980,
      "last_requested_at": "2026-03-26T14:00:00+00:00",
      "buckets": [
        {
          "bucket_start": "2026-03-24T00:00:00+00:00",
          "total_requests": 10,
          "num_input_records": 300,
          "num_resolvable_records": 280,
          "num_matches": 250
        },
        {
          "bucket_start": "2026-03-25T00:00:00+00:00",
          "total_requests": 12,
          "num_input_records": 350,
          "num_resolvable_records": 320,
          "num_matches": 285
        },
        {
          "bucket_start": "2026-03-26T00:00:00+00:00",
          "total_requests": 20,
          "num_input_records": 550,
          "num_resolvable_records": 500,
          "num_matches": 445
        }
      ],
      "overall_match_rate": 0.8166666666666667,
      "resolvable_match_rate": 0.8909090909090909
    },
    {
      "endpoint": "v2/enrich",
      "total_requests": 8,
      "num_input_records": 150,
      "num_resolvable_records": 150,
      "num_matches": 150,
      "last_requested_at": "2026-03-25T09:30:00+00:00",
      "buckets": [
        {
          "bucket_start": "2026-03-24T00:00:00+00:00",
          "total_requests": 2,
          "num_input_records": 40,
          "num_resolvable_records": 40,
          "num_matches": 40
        },
        {
          "bucket_start": "2026-03-25T00:00:00+00:00",
          "total_requests": 6,
          "num_input_records": 110,
          "num_resolvable_records": 110,
          "num_matches": 110
        },
        {
          "bucket_start": "2026-03-26T00:00:00+00:00",
          "total_requests": 0,
          "num_input_records": 0,
          "num_resolvable_records": 0,
          "num_matches": 0
        }
      ],
      "overall_match_rate": 1.0,
      "resolvable_match_rate": 1.0
    }
  ],
  "request_completed_at": "2026-03-26T14:05:12.123456Z"
}

Overview

The Endpoint Usage endpoint returns organization-wide usage metrics for the Minerva API endpoints your organization is allowed to access. Each result is grouped by endpoint, such as v1/resolve or v2/enrich, and includes aggregate counts for:

Total requests
Total input records
Total resolvable records
Total matches
Computed match rates
Last request timestamp

If you provide both start_date and end_date, the response also includes a buckets array for each endpoint so you can chart usage over time.

curl --request GET \
  --url 'https://api.minerva.io/usage' \
  --header 'x-api-key: <api-key>' \
  --get \
  --data-urlencode 'start_date=2026-03-01' \
  --data-urlencode 'end_date=2026-03-26' \
  --data-urlencode 'bucketing_size=day' \
  --data-urlencode 'timezone=UTC' \
  --data-urlencode 'include_unused_endpoints=false'

Request

Headers

string

required

Your API key for authentication.

Query Parameters

string

Optional start date in YYYY-MM-DD format. Must be provided together with end_date. When both dates are present, the response includes bucketed usage data.

string

Optional end date in YYYY-MM-DD format. Must be provided together with start_date. The date range is inclusive in the requested timezone.

string

Optional bucket frequency. Supported values are hour, day, week, month, quarter, and year. Defaults to day.

string

Optional IANA timezone name, such as UTC or America/New_York. Defaults to UTC.

boolean

Optional flag indicating whether endpoints with zero usage should be included in the response. Defaults to false.

Request Notes

There is no request body.
start_date and end_date must be supplied together or omitted together.

Response

Success Response

string

Unique identifier for this request, useful for support and debugging.

array

Array of endpoint usage summary objects for the requester’s organization.

string

ISO 8601 timestamp indicating when the request finished.

Result Object

string

Endpoint identifier in version/path format, such as v1/resolve or v2/enrich.

integer

Total number of API requests made to this endpoint for the selected organization and date range.

integer

Total number of input records submitted to this endpoint.

integer

Total number of records that were considered resolvable for this endpoint.

integer

Total number of matched records produced by this endpoint.

number

Computed as num_matches / num_input_records. Returns 0.0 when no input records exist.

number

Computed as num_matches / num_resolvable_records. Returns 0.0 when no resolvable records exist.

string

Timestamp of the most recent request for this endpoint in the selected range. Can be null for unused endpoints when include_unused_endpoints=true.

array

Array of bucket objects when both start_date and end_date are provided. Otherwise this field is null.

Bucket Object

string

Start timestamp for the bucket in the requested timezone.

integer

Number of requests in this bucket.

integer

Number of input records in this bucket.

integer

Number of resolvable records in this bucket.

integer

Number of matched records in this bucket.

{
  "api_request_id": "req_usage_12345",
  "results": [
    {
      "endpoint": "v1/resolve",
      "total_requests": 42,
      "num_input_records": 1200,
      "num_resolvable_records": 1100,
      "num_matches": 980,
      "last_requested_at": "2026-03-26T14:00:00+00:00",
      "buckets": [
        {
          "bucket_start": "2026-03-24T00:00:00+00:00",
          "total_requests": 10,
          "num_input_records": 300,
          "num_resolvable_records": 280,
          "num_matches": 250
        },
        {
          "bucket_start": "2026-03-25T00:00:00+00:00",
          "total_requests": 12,
          "num_input_records": 350,
          "num_resolvable_records": 320,
          "num_matches": 285
        },
        {
          "bucket_start": "2026-03-26T00:00:00+00:00",
          "total_requests": 20,
          "num_input_records": 550,
          "num_resolvable_records": 500,
          "num_matches": 445
        }
      ],
      "overall_match_rate": 0.8166666666666667,
      "resolvable_match_rate": 0.8909090909090909
    },
    {
      "endpoint": "v2/enrich",
      "total_requests": 8,
      "num_input_records": 150,
      "num_resolvable_records": 150,
      "num_matches": 150,
      "last_requested_at": "2026-03-25T09:30:00+00:00",
      "buckets": [
        {
          "bucket_start": "2026-03-24T00:00:00+00:00",
          "total_requests": 2,
          "num_input_records": 40,
          "num_resolvable_records": 40,
          "num_matches": 40
        },
        {
          "bucket_start": "2026-03-25T00:00:00+00:00",
          "total_requests": 6,
          "num_input_records": 110,
          "num_resolvable_records": 110,
          "num_matches": 110
        },
        {
          "bucket_start": "2026-03-26T00:00:00+00:00",
          "total_requests": 0,
          "num_input_records": 0,
          "num_resolvable_records": 0,
          "num_matches": 0
        }
      ],
      "overall_match_rate": 1.0,
      "resolvable_match_rate": 1.0
    }
  ],
  "request_completed_at": "2026-03-26T14:05:12.123456Z"
}

Behavior Notes

Results are returned at the organization level, not the individual user level.
If you omit the date range, aggregate totals are still returned, but buckets will be null.
If include_unused_endpoints=true, endpoints with no usage can be returned with zero counts and last_requested_at: null.
Results are sorted by num_matches in descending order.

Error Responses

Common Errors

400 - Bad Request: Invalid timezone, only one of start_date or end_date was supplied, or the requester organization could not be determined
401 - Unauthorized: Invalid or missing API key
405 - Method Not Allowed: Using a method other than GET
422 - Unprocessable Entity: Invalid query parameter type or unsupported bucketing_size
500 - Internal Server Error: Unexpected server error

Error Examples

Only one date provided:

{
  "code": "bad_request",
  "message": "Both start_date and end_date must be provided, or neither."
}

Invalid timezone:

{
  "code": "bad_request",
  "message": "Invalid timezone: Mars/Phobos"
}

Common Integration Patterns

Pattern 1: Daily endpoint usage dashboard

response = minerva_api.get(
    "/usage",
    params={
        "start_date": "2026-03-01",
        "end_date": "2026-03-31",
        "bucketing_size": "day",
        "timezone": "UTC"
    }
)

for endpoint in response["results"]:
    print(endpoint["endpoint"], endpoint["total_requests"])

Pattern 2: Discover all available endpoints for your org

response = minerva_api.get(
    "/usage",
    params={"include_unused_endpoints": "true"}
)

all_endpoints = [item["endpoint"] for item in response["results"]]

⌘I

Getting Started

Core Endpoints

Validation Workflows

Person Search

Usage

Storage

Segments

Quick Answer

Overview

Request

Headers

Query Parameters

Request Notes

Response

Success Response

Result Object

Bucket Object

Behavior Notes

Error Responses

Common Errors

Error Examples

Common Integration Patterns

​Quick Answer

​Overview

​Request

​Headers

​Query Parameters

​Request Notes

​Response

​Success Response

​Result Object

​Bucket Object

​Behavior Notes

​Error Responses

​Common Errors

​Error Examples

​Common Integration Patterns

Quick Answer

Overview

Request

Headers

Query Parameters

Request Notes

Response

Success Response

Result Object

Bucket Object

Behavior Notes

Error Responses

Common Errors

Error Examples

Common Integration Patterns