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
string
required
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
string
no_plan, trial, active or suspended.string or null
trial_expired, delinquent or contract_ended, when applicable.string or null
growth or enterprise, when applicable.object or null
Current usable contract or Trial term. Also null for Unlimited Enterprise.
string
ISO 8601 timestamp of the summary evaluation.
string
Present for agency-managed organizations: billing parent’s display name.
boolean
Present for agency-managed organizations: whether the shared billing account permits product access.
Current Term Object
string
trial or contract.string
growth or enterprise.string
ISO 8601 timestamp when the term starts.
string
ISO 8601 timestamp when the term ends.
integer
Released, unexpired allowance; excludes future releases.
integer
Reserved plus finalized records funded by that allowance.
integer
Remaining included record allowance.
string or null
Next regular plan allowance release within the term, if any.
integer
Records in that next release; zero when none is scheduled.
object or null
Current contract-month overage; null for Trial.
integer
Remaining allowance plus overage capacity for additional unique record exports.
Overage Object
All monetary fields are in USD cents and can contain fractional cents.integer
Reserved plus finalized overage records in the current contract month.
integer
Additional records fundable by the remaining spend limit.
boolean
No allowance remains and the remaining spend cannot fund another record.
number
Price per overage record.
number
Overage records multiplied by the rate, including reservations.
number
Monthly billable-usage cap, excluding the base subscription.
number
Remaining headroom under that cap.
used_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?