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

# Billing Usage

> Check remaining record allowance, overage spend and current record export capacity

<div style={{ display: 'none' }} aria-hidden="false">
  ## Quick Answer

  **How much record allowance does my organization have left?** Use this endpoint to check remaining included allowance, overage spend and capacity for additional unique record exports.

  **Common questions this endpoint answers:**

  * How much included record allowance remains?
  * When will the next allowance be released?
  * How much overage spend remains under our monthly limit?
  * What is our current billing access status?

  **What you get back:** An organization-wide billing summary with the current term, remaining allowance and overage capacity.
</div>

## Overview

Returns the current billing summary for the organization associated with your API
key. It covers organization-wide record exports across channels, not just
API activity. For API request counts and historical buckets, use
[Endpoint Usage](/api-reference/usage-endpoints).

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

## Request

### Headers

<ParamField header="x-api-key" type="string" required>
  Your organization's API key. Your organization must have Data API access.
  No billing management permission is required.
</ParamField>

### Request Notes

* There are no query parameters or request body.
* The organization comes from your authenticated key; you cannot select another organization.

## Response

The response is a single object, without a `results` wrapper.
Responses use `Cache-Control: no-store`.

### Success Response

<ResponseField name="access_status" type="string">
  `no_plan`, `trial`, `active` or `suspended`.
</ResponseField>

<ResponseField name="access_reason" type="string or null">
  `trial_expired`, `delinquent` or `contract_ended`, when applicable.
</ResponseField>

<ResponseField name="product_tier" type="string or null">
  `growth` or `enterprise`, when applicable.
</ResponseField>

<ResponseField name="current_term" type="object or null">
  Current usable contract or Trial term. Also null for Unlimited Enterprise.
</ResponseField>

<ResponseField name="request_completed_at" type="string">
  ISO 8601 timestamp of the summary evaluation.
</ResponseField>

<ResponseField name="managed_by" type="string">
  Present for agency-managed organizations: billing parent's display name.
</ResponseField>

<ResponseField name="has_product_access" type="boolean">
  Present for agency-managed organizations: whether the shared billing account permits product access.
</ResponseField>

### Current Term Object

<ResponseField name="term_type" type="string">
  `trial` or `contract`.
</ResponseField>

<ResponseField name="product_tier" type="string">
  `growth` or `enterprise`.
</ResponseField>

<ResponseField name="starts_at" type="string">
  ISO 8601 timestamp when the term starts.
</ResponseField>

<ResponseField name="ends_at" type="string">
  ISO 8601 timestamp when the term ends.
</ResponseField>

<ResponseField name="allowance.granted_records" type="integer">
  Released, unexpired allowance; excludes future releases.
</ResponseField>

<ResponseField name="allowance.used_records" type="integer">
  Reserved plus finalized records funded by that allowance.
</ResponseField>

<ResponseField name="allowance.available_records" type="integer">
  Remaining included record allowance.
</ResponseField>

<ResponseField name="allowance.next_release_at" type="string or null">
  Next regular plan allowance release within the term, if any.
</ResponseField>

<ResponseField name="allowance.next_release_records" type="integer">
  Records in that next release; zero when none is scheduled.
</ResponseField>

<ResponseField name="overage" type="object or null">
  Current contract-month overage; null for Trial.
</ResponseField>

<ResponseField name="full_record_capacity_available" type="integer">
  Remaining allowance plus overage capacity for additional unique record exports.
</ResponseField>

### Overage Object

All monetary fields are in **USD cents** and can contain fractional cents.

<ResponseField name="used_records" type="integer">
  Reserved plus finalized overage records in the current contract month.
</ResponseField>

<ResponseField name="available_records" type="integer">
  Additional records fundable by the remaining spend limit.
</ResponseField>

<ResponseField name="limit_reached" type="boolean">
  No allowance remains and the remaining spend cannot fund another record.
</ResponseField>

<ResponseField name="unit_rate_cents" type="number">
  Price per overage record.
</ResponseField>

<ResponseField name="committed_spend_cents" type="number">
  Overage records multiplied by the rate, including reservations.
</ResponseField>

<ResponseField name="spend_limit_cents" type="number">
  Monthly billable-usage cap, excluding the base subscription.
</ResponseField>

<ResponseField name="remaining_spend_cents" type="number">
  Remaining headroom under that cap.
</ResponseField>

For agency-managed organizations, the service returns shared record capacity
from the billing parent. Overage contains only `used_records`,
`available_records` and `limit_reached`; prices and spend amounts are omitted.

<ResponseExample>
  ```json 200 theme={null}
  {
    "access_status": "active",
    "access_reason": null,
    "product_tier": "growth",
    "current_term": {
      "term_type": "contract",
      "product_tier": "growth",
      "starts_at": "2026-10-01T00:00:00Z",
      "ends_at": "2027-10-01T00:00:00Z",
      "allowance": {
        "granted_records": 1000,
        "used_records": 700,
        "available_records": 300,
        "next_release_at": "2026-11-01T00:00:00Z",
        "next_release_records": 1000
      },
      "overage": {
        "unit_rate_cents": 40.0,
        "used_records": 5,
        "committed_spend_cents": 200.0,
        "spend_limit_cents": 40000.0,
        "remaining_spend_cents": 39800.0,
        "available_records": 995,
        "limit_reached": false
      },
      "full_record_capacity_available": 1295
    },
    "request_completed_at": "2026-10-06T12:00:00Z"
  }
  ```
</ResponseExample>

## Behavior Notes

* Record allowance measures unique people exported during the contract term.
  Re-exporting a record already licensed in that term does not consume another
  unit of allowance.
* Usage includes in-flight reservations, so committed spend is not an invoice
  or payment total.
* A read does not reserve capacity. Concurrent exports can change availability
  before your next request. Other operational limits still apply.
* A null `current_term` does not mean zero capacity by itself. An active
  Unlimited Enterprise account has no enforced allowance or overage limit and
  returns `current_term: null`. Check `access_status` and `product_tier` together.

## Error Responses

### Common Errors

* `401` - **Unauthorized**: Invalid or missing API key
* `403` - **Forbidden**: Your API key or organization does not have access to this endpoint
* `503` - **Service Unavailable**: Billing usage is temporarily unavailable. Retry later; this does not mean your usage is zero.

### Error Example

```json theme={null}
{
  "code": "billing_usage_unavailable",
  "message": "Billing usage is temporarily unavailable"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.