API reference

Usage for the current billing period

GET/v1/usage

Billing periods are UTC calendar months. Every enrichment that returns a merchant counts as one billable unit, whether it came from the cache or the AI; results with merchant: null are free. usage is current to the request; daily can lag by a few seconds.

Response

Field	Type	Description
`request_id`required	string	Unique ID of this request.
`period`required	object
`start`required	string
`end`required	string
`plan`required	object
`id`required	string
`name`required	string
`monthly_quota`required	integer \| null	Null for custom (unlimited) plans.
`requests_per_second`required	number
`usage`required	object
`billable`required	integer
`remaining`required	integer \| null
`daily`required	object[]
`date`required	string
`requests`required	integer
`billable`required	integer
`cache_hits`required	integer
`ai_calls`required	integer

Status codes

200
The caller's plan and usage.
401
Missing, invalid or revoked API key, or a suspended account.
Error code unauthorized
429
Too many requests per second. Retry after the number of seconds in Retry-After.
Error code rate_limited

$ch = curl_init("https://api.descriptorapi.com/v1/usage"); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('DESCRIPTORAPI_KEY')], ]); $data = json_decode(curl_exec($ch), true);

{ "request_id": "req_01JABCDEF0123456789ABCDEFG", "period": { "start": "2026-10-01", "end": "2026-10-31" }, "plan": { "id": "free", "name": "Free", "monthly_quota": 500, "requests_per_second": 2 }, "usage": { "billable": 120, "remaining": 380 }, "daily": [ { "date": "2026-10-12", "requests": 150, "billable": 120, "cache_hits": 90, "ai_calls": 4 } ] }