List billing usage ledger entries
Returns a cursor-paginated, append-only ledger of your organization's billable events (one row per outbound segment, one per inbound segment, and so on). This ledger is the source of truth for cost reconciliation.
Range defaults and limits:
fromandtodefault to the last 30 days when omitted.- The explicit
to - fromwindow is capped at 90 days; larger ranges return422 VALIDATION_FAILEDwithdetails.range. The NDJSON export bypasses this cap. limitdefaults to100, with a maximum of500.
To stream a full export, send Accept: application/x-ndjson. The
response is 200 OK with Content-Type: application/x-ndjson, one JSON
object per line and no envelope wrapper, and the 90-day cap does not
apply.
Cost fields are snapshotted at write time, so a later price change does not retroactively alter past ledger rows.
Requires the billing:read scope.
Authenticate by sending your API key as a bearer token:
Authorization: Bearer am_live_.... Every request is automatically
scoped to the organization that owns the key and to the scopes granted
to that key.
In: header
Query Parameters
date-timedate-time1001 <= value <= 500Header Parameters
Response Body
application/json
application/json
application/json
curl -X GET "https://example.com/v1/billing/usage"{
"success": true,
"data": [
{
"id": "8f3a2b1c-1c2d-4e5f-9a8b-0c1d2e3f4a5b",
"ts": "2026-04-26T11:59:00Z",
"kind": "number_month",
"quantity": 1,
"unit_cost_cents": 94,
"total_cents": 94,
"ref_kind": null,
"ref_id": null,
"metadata": {
"resource_id": "7c1f0a2d-9e8b-4c3a-9d2e-1f0a2b3c4d5e"
}
}
],
"meta": {
"total": 0,
"limit": 100,
"offset": 0,
"next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wNC0yNlQxMTo1OTowMFoiLCJpZCI6IjhmM2EyYjFjLTFjMmQtNGU1Zi05YThiLTBjMWQyZTNmNGE1YiJ9"
}
}{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "authentication failed",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}{
"success": false,
"error": {
"code": "FORBIDDEN",
"message": "missing required scope",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}{
"success": false,
"error": {
"code": "VALIDATION_FAILED",
"message": "validation failed",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM",
"details": {
"to": "must be E.164",
"body": "must be 1..1600 chars"
}
}
}