curl --request GET \
--url 'https://api.minerva.io/billing/usage' \
--header 'x-api-key: <api-key>'
{
"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"
}
Usage
Billing Usage
Check remaining record allowance, overage spend and current record export capacity
GET
/
billing
/
usage
curl --request GET \
--url 'https://api.minerva.io/billing/usage' \
--header 'x-api-key: <api-key>'
{
"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"
}
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?
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.curl --request GET \
--url 'https://api.minerva.io/billing/usage' \
--header 'x-api-key: <api-key>'
Request
Headers
Your organization’s API key. Your organization must have Data API access.
No billing management permission is required.
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 aresults wrapper.
Responses use Cache-Control: no-store.
Success Response
Present for agency-managed organizations: whether the shared billing account permits product access.
Current Term Object
Overage Object
All monetary fields are in USD cents and can contain fractional cents. For agency-managed organizations, the service returns shared record capacity from the billing parent. Overage contains onlyused_records,
available_records and limit_reached; prices and spend amounts are omitted.
{
"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"
}
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_termdoes not mean zero capacity by itself. An active Unlimited Enterprise account has no enforced allowance or overage limit and returnscurrent_term: null. Checkaccess_statusandproduct_tiertogether.
Error Responses
Common Errors
401- Unauthorized: Invalid or missing API key403- Forbidden: Your API key or organization does not have access to this endpoint503- Service Unavailable: Billing usage is temporarily unavailable. Retry later; this does not mean your usage is zero.
Error Example
{
"code": "billing_usage_unavailable",
"message": "Billing usage is temporarily unavailable"
}
Was this page helpful?