Skip to main content
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"
}

​
Quick Answer

How do I see API usage for my organization? Use this endpoint to retrieve org-wide usage metrics for the Minerva API endpoints your organization can access.Common questions this endpoint answers:
  • Which Minerva endpoints has my organization used?
  • How many requests did we make to each endpoint?
  • How many input records, resolvable records, and matches did each endpoint produce?
  • When was each endpoint last used?
  • How can I get usage buckets over time for reporting?
What you get back: A list of endpoint-level usage summaries for your organization, with optional time buckets when you provide a date range.

​
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

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

​
Query Parameters

​
start_date
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.
​
end_date
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.
​
bucketing_size
string
Optional bucket frequency. Supported values are hour, day, week, month, quarter, and year. Defaults to day.
​
timezone
string
Optional IANA timezone name, such as UTC or America/New_York. Defaults to UTC.
​
include_unused_endpoints
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

​
api_request_id
string
Unique identifier for this request, useful for support and debugging.
​
results
array
Array of endpoint usage summary objects for the requester’s organization.
​
request_completed_at
string
ISO 8601 timestamp indicating when the request finished.

​
Result Object

​
endpoint
string
Endpoint identifier in version/path format, such as v1/resolve or v2/enrich.
​
total_requests
integer
Total number of API requests made to this endpoint for the selected organization and date range.
​
num_input_records
integer
Total number of input records submitted to this endpoint.
​
num_resolvable_records
integer
Total number of records that were considered resolvable for this endpoint.
​
num_matches
integer
Total number of matched records produced by this endpoint.
​
overall_match_rate
number
Computed as num_matches / num_input_records. Returns 0.0 when no input records exist.
​
resolvable_match_rate
number
Computed as num_matches / num_resolvable_records. Returns 0.0 when no resolvable records exist.
​
last_requested_at
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.
​
buckets
array
Array of bucket objects when both start_date and end_date are provided. Otherwise this field is null.

​
Bucket Object

​
bucket_start
string
Start timestamp for the bucket in the requested timezone.
​
total_requests
integer
Number of requests in this bucket.
​
num_input_records
integer
Number of input records in this bucket.
​
num_resolvable_records
integer
Number of resolvable records in this bucket.
​
num_matches
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: 
{
  "error": "Bad Request",
  "message": "Both start_date and end_date must be provided, or neither."
}
Invalid timezone: 
{
  "error": "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"]]