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

# Endpoint Usage

> Retrieve org-wide API usage metrics for the endpoints available to your organization

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

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

<RequestExample>
  ```bash Request Example theme={null}
  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'
  ```
</RequestExample>

## Request

### Headers

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

### Query Parameters

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

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

<ParamField query="bucketing_size" type="string">
  Optional bucket frequency. Supported values are `hour`, `day`, `week`, `month`, `quarter`, and `year`. Defaults to `day`.
</ParamField>

<ParamField query="timezone" type="string">
  Optional IANA timezone name, such as `UTC` or `America/New_York`. Defaults to `UTC`.
</ParamField>

<ParamField query="include_unused_endpoints" type="boolean">
  Optional flag indicating whether endpoints with zero usage should be included in the response. Defaults to `false`.
</ParamField>

### Request Notes

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

## Response

### Success Response

<ResponseField name="api_request_id" type="string">
  Unique identifier for this request, useful for support and debugging.
</ResponseField>

<ResponseField name="results" type="array">
  Array of endpoint usage summary objects for the requester's organization.
</ResponseField>

<ResponseField name="request_completed_at" type="string">
  ISO 8601 timestamp indicating when the request finished.
</ResponseField>

### Result Object

<ResponseField name="endpoint" type="string">
  Endpoint identifier in `version/path` format, such as `v1/resolve` or `v2/enrich`.
</ResponseField>

<ResponseField name="total_requests" type="integer">
  Total number of API requests made to this endpoint for the selected organization and date range.
</ResponseField>

<ResponseField name="num_input_records" type="integer">
  Total number of input records submitted to this endpoint.
</ResponseField>

<ResponseField name="num_resolvable_records" type="integer">
  Total number of records that were considered resolvable for this endpoint.
</ResponseField>

<ResponseField name="num_matches" type="integer">
  Total number of matched records produced by this endpoint.
</ResponseField>

<ResponseField name="overall_match_rate" type="number">
  Computed as `num_matches / num_input_records`. Returns `0.0` when no input records exist.
</ResponseField>

<ResponseField name="resolvable_match_rate" type="number">
  Computed as `num_matches / num_resolvable_records`. Returns `0.0` when no resolvable records exist.
</ResponseField>

<ResponseField name="last_requested_at" type="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`.
</ResponseField>

<ResponseField name="buckets" type="array">
  Array of bucket objects when both `start_date` and `end_date` are provided. Otherwise this field is `null`.
</ResponseField>

### Bucket Object

<ResponseField name="bucket_start" type="string">
  Start timestamp for the bucket in the requested timezone.
</ResponseField>

<ResponseField name="total_requests" type="integer">
  Number of requests in this bucket.
</ResponseField>

<ResponseField name="num_input_records" type="integer">
  Number of input records in this bucket.
</ResponseField>

<ResponseField name="num_resolvable_records" type="integer">
  Number of resolvable records in this bucket.
</ResponseField>

<ResponseField name="num_matches" type="integer">
  Number of matched records in this bucket.
</ResponseField>

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

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

```json theme={null}
{
  "error": "Bad Request",
  "message": "Both start_date and end_date must be provided, or neither."
}
```

**Invalid timezone:**

```json theme={null}
{
  "error": "Bad Request",
  "message": "Invalid timezone: Mars/Phobos"
}
```

## Common Integration Patterns

**Pattern 1: Daily endpoint usage dashboard**

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

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

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