curl --request GET \
--url https://api.aireserve.com/v1/customers/usage \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.aireserve.com/v1/customers/usage"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.aireserve.com/v1/customers/usage', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"period": {
"start": "<string>",
"end": "<string>"
},
"currency": "USD",
"has_pricing_rules": true,
"truncated": true,
"customers": [
{
"customer_id": "<string>",
"requests": 4503599627370495,
"prompt_tokens": 4503599627370495,
"completion_tokens": 4503599627370495,
"cost_usd": "<string>",
"priced": true,
"billable_usd": "<string>",
"margin_usd": "<string>",
"margin_pct": 123
}
],
"untagged": {
"requests": 4503599627370495,
"total_tokens": 4503599627370495,
"cost_usd": "<string>"
},
"totals": {
"requests": 4503599627370495,
"prompt_tokens": 4503599627370495,
"completion_tokens": 4503599627370495,
"cost_usd": "<string>",
"priced": true,
"billable_usd": "<string>",
"margin_usd": "<string>",
"margin_pct": 123
}
}{
"error": {
"message": "<string>",
"type": "invalid_request_error",
"param": "<string>",
"code": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "invalid_request_error",
"param": "<string>",
"code": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "invalid_request_error",
"param": "<string>",
"code": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "invalid_request_error",
"param": "<string>",
"code": "<string>"
}
}Usage and billable amounts per end customer
What each of your end customers used in the period, what it cost your organization (cost_usd), and — when your organization has pricing rules for its customers — what the customer owes (billable_usd) and your margin. Customers are the opaque ids you tagged requests with via x-aireserve-customer (or the OpenAI user field). Requests with no tag are reported once as untagged, cost only. Failed requests are never billed and are not counted in requests.
curl --request GET \
--url https://api.aireserve.com/v1/customers/usage \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.aireserve.com/v1/customers/usage"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.aireserve.com/v1/customers/usage', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"period": {
"start": "<string>",
"end": "<string>"
},
"currency": "USD",
"has_pricing_rules": true,
"truncated": true,
"customers": [
{
"customer_id": "<string>",
"requests": 4503599627370495,
"prompt_tokens": 4503599627370495,
"completion_tokens": 4503599627370495,
"cost_usd": "<string>",
"priced": true,
"billable_usd": "<string>",
"margin_usd": "<string>",
"margin_pct": 123
}
],
"untagged": {
"requests": 4503599627370495,
"total_tokens": 4503599627370495,
"cost_usd": "<string>"
},
"totals": {
"requests": 4503599627370495,
"prompt_tokens": 4503599627370495,
"completion_tokens": 4503599627370495,
"cost_usd": "<string>",
"priced": true,
"billable_usd": "<string>",
"margin_usd": "<string>",
"margin_pct": 123
}
}{
"error": {
"message": "<string>",
"type": "invalid_request_error",
"param": "<string>",
"code": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "invalid_request_error",
"param": "<string>",
"code": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "invalid_request_error",
"param": "<string>",
"code": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "invalid_request_error",
"param": "<string>",
"code": "<string>"
}
}Authorizations
Your AI Reserve API key (aireserve_api_…) from the API Keys page in the portal (https://portal.aireserve.com/keys).
Query Parameters
Inclusive start of the period: a UTC date (2026-10-01) or an RFC 3339 timestamp. Defaults to 30 days before end.
Exclusive end of the period: a UTC date or an RFC 3339 timestamp. Defaults to now. The period may span at most 92 days.
Response
OK
The period the figures cover.
Show child attributes
Show child attributes
USD Whether at least one of your pricing rules applies to the period. When false, billable_usd and margin fields are omitted everywhere.
True when the period held more rows than one response carries and the cheapest were dropped. Narrow the period or query one customer.
One row per tagged customer, highest cost first.
Show child attributes
Show child attributes
Usage with no x-aireserve-customer tag. Cost only — untagged requests are never priced. Sourced from hourly aggregates, so it can trail live traffic by a few minutes.
Show child attributes
Show child attributes
Sum over every tagged customer in the period.
Show child attributes
Show child attributes