/api/orgs/{org_id}/spend/viewRead a report and its chart
Body is a frozen SpendQuery with its registered as_of and snapshot_id. Returns the report and the selected dimension's series at that snapshot; never starts new work. 409 snapshot_invalidated means report and chart no longer match. API keys need provisioning strength and scope: org.
Authentication: Bearer API key in the Authorization header
Path parameters
org_idstringrequiredYour organization id (uuid).
GET /api/whoamireturns it.
Request body
startstringrequiredInclusive start, with a UTC offset.
endstringrequiredExclusive end, with a UTC offset. Must be after
start.time_zonestringIANA zone for day and month buckets.
scopeanybasisanygroup_byanytag_keystring | nullRequired exactly when
group_byistag.grainanyfiltersarray<object>At most one filter per dimension.
filters
dimensionenumrequiredGrouping and filter dimension.
keyandmembervalues are uuids.tagis only agroup_by(withtag_key); filter tags throughtags.valuesarray<string>missingbooleanAlso match calls with no value for this dimension.
excludebooleanInvert the predicate. Must be a JSON boolean.
tagsarray<object>At most one predicate per tag key.
tags
keystringrequiredvaluesarray<string>missingbooleanAlso match calls without this tag key.
excludeboolean
sortanydirectionenumoffsetintegerlimitintegeras_ofstring | nullReport cutoff. Server-set on the first read; not in the future and not before
start.snapshot_idstringRegistered snapshot token. Requires its original
as_of. Omitted from responses when unset.
Responses
200OK
Response
reportobjectrequiredSummary, chart buckets and a page of the breakdown for one frozen query.
queryis the frozen query to send back for the next page (offset: next_offset).report
queryobjectrequiredA bounded report slice.
endis exclusive; the range is at most ten years. Omitas_ofandsnapshot_idfor a fresh read; the response returns them frozen, and later reads (pagination, view, series, facets, activity, export) send them back unchanged so every panel reads one snapshot.query
startstringrequiredInclusive start, with a UTC offset.
endstringrequiredExclusive end, with a UTC offset. Must be after
start.time_zonestringIANA zone for day and month buckets.
scopeanybasisanygroup_byanytag_keystring | nullRequired exactly when
group_byistag.grainanyfiltersarray<object>At most one filter per dimension.
filters
dimensionenumrequiredGrouping and filter dimension.
keyandmembervalues are uuids.tagis only agroup_by(withtag_key); filter tags throughtags.valuesarray<string>missingbooleanAlso match calls with no value for this dimension.
excludebooleanInvert the predicate. Must be a JSON boolean.
tagsarray<object>At most one predicate per tag key.
tags
keystringrequiredvaluesarray<string>missingbooleanAlso match calls without this tag key.
excludeboolean
sortanydirectionenumoffsetintegerlimitintegeras_ofstring | nullReport cutoff. Server-set on the first read; not in the future and not before
start.snapshot_idstringRegistered snapshot token. Requires its original
as_of. Omitted from responses when unset.
totalsobjectrequiredExact counters and money legs for one basis. The all-in spend is paid + BYOK + free.
totals
countintegerrequiredSettled requests (or terminal attempts on the attempts basis); not a success count.
rejected_countintegerrequiredFailed or expired requests with no provider dispatch (always 0 on the attempts basis).
errorsintegerrequiredNon-completed requests or attempts, rejections included.
input_tokensintegerrequiredoutput_tokensintegerrequiredcached_input_tokensintegerrequiredreasoning_tokensintegerrequiredpaid_nano_usdstringrequiredCharged credits. Integer nano-USD as a decimal string (1 USD = 1,000,000,000) so JavaScript cannot round it.
byok_nano_usdstringrequiredBring-your-own-key list estimate; never charged. Integer nano-USD as a decimal string (1 USD = 1,000,000,000) so JavaScript cannot round it.
free_nano_usdstringrequiredFree promotional usage at list value; not a credit debit. Integer nano-USD as a decimal string (1 USD = 1,000,000,000) so JavaScript cannot round it.
unknown_usage_countintegerrequiredUsage whose provider accounting is unknown. Nonzero makes the money provisional.
bucketsarray<object>requiredbuckets
startstringrequiredfiguresobjectrequiredExact counters and money legs for one basis. The all-in spend is paid + BYOK + free.
figures
countintegerrequiredSettled requests (or terminal attempts on the attempts basis); not a success count.
rejected_countintegerrequiredFailed or expired requests with no provider dispatch (always 0 on the attempts basis).
errorsintegerrequiredNon-completed requests or attempts, rejections included.
input_tokensintegerrequiredoutput_tokensintegerrequiredcached_input_tokensintegerrequiredreasoning_tokensintegerrequiredpaid_nano_usdstringrequiredCharged credits. Integer nano-USD as a decimal string (1 USD = 1,000,000,000) so JavaScript cannot round it.
byok_nano_usdstringrequiredBring-your-own-key list estimate; never charged. Integer nano-USD as a decimal string (1 USD = 1,000,000,000) so JavaScript cannot round it.
free_nano_usdstringrequiredFree promotional usage at list value; not a credit debit. Integer nano-USD as a decimal string (1 USD = 1,000,000,000) so JavaScript cannot round it.
unknown_usage_countintegerrequiredUsage whose provider accounting is unknown. Nonzero makes the money provisional.
groupsarray<object>requiredgroups
valuestring | nullrequiredlabelstring | nullrequiredfiguresobjectrequiredExact counters and money legs for one basis. The all-in spend is paid + BYOK + free.
figures
countintegerrequiredSettled requests (or terminal attempts on the attempts basis); not a success count.
rejected_countintegerrequiredFailed or expired requests with no provider dispatch (always 0 on the attempts basis).
errorsintegerrequiredNon-completed requests or attempts, rejections included.
input_tokensintegerrequiredoutput_tokensintegerrequiredcached_input_tokensintegerrequiredreasoning_tokensintegerrequiredpaid_nano_usdstringrequiredCharged credits. Integer nano-USD as a decimal string (1 USD = 1,000,000,000) so JavaScript cannot round it.
byok_nano_usdstringrequiredBring-your-own-key list estimate; never charged. Integer nano-USD as a decimal string (1 USD = 1,000,000,000) so JavaScript cannot round it.
free_nano_usdstringrequiredFree promotional usage at list value; not a credit debit. Integer nano-USD as a decimal string (1 USD = 1,000,000,000) so JavaScript cannot round it.
unknown_usage_countintegerrequiredUsage whose provider accounting is unknown. Nonzero makes the money provisional.
filter_labelsarray<object>filter_labels
valuestring | nullrequiredlabelstringrequireddimensionenumrequiredGrouping and filter dimension.
keyandmembervalues are uuids.tagis only agroup_by(withtag_key); filter tags throughtags.tag_keystring | null
group_countintegerrequirednext_offsetinteger | nullNull on the last page.
coverageobjectrequiredProjection freshness, independent of whether the slice is empty.
coverage
as_ofstringrequiredprojected_throughstring | nullrequiredcompletebooleanrequiredpending_requestsintegerrequiredincludes_pre_admission_rejectionsboolean
seriesobjectrequiredOne of
object
statusanyrequireddataobjectrequiredUp to seven spend-ranked values of the query's
group_byplus the remainder, stacked per bucket.data
queryobjectrequiredA bounded report slice.
endis exclusive; the range is at most ten years. Omitas_ofandsnapshot_idfor a fresh read; the response returns them frozen, and later reads (pagination, view, series, facets, activity, export) send them back unchanged so every panel reads one snapshot.query
startstringrequiredInclusive start, with a UTC offset.
endstringrequiredExclusive end, with a UTC offset. Must be after
start.time_zonestringIANA zone for day and month buckets.
scopeanybasisanygroup_byanytag_keystring | nullRequired exactly when
group_byistag.grainanyfiltersarray<object>At most one filter per dimension.
filters
dimensionenumrequiredGrouping and filter dimension.
keyandmembervalues are uuids.tagis only agroup_by(withtag_key); filter tags throughtags.valuesarray<string>missingbooleanAlso match calls with no value for this dimension.
excludebooleanInvert the predicate. Must be a JSON boolean.
tagsarray<object>At most one predicate per tag key.
tags
keystringrequiredvaluesarray<string>missingbooleanAlso match calls without this tag key.
excludeboolean
sortanydirectionenumoffsetintegerlimitintegeras_ofstring | nullReport cutoff. Server-set on the first read; not in the future and not before
start.snapshot_idstringRegistered snapshot token. Requires its original
as_of. Omitted from responses when unset.
coverageobjectrequiredProjection freshness, independent of whether the slice is empty.
coverage
as_ofstringrequiredprojected_throughstring | nullrequiredcompletebooleanrequiredpending_requestsintegerrequiredincludes_pre_admission_rejectionsboolean
totalsobjectrequiredExact counters and money legs for one basis. The all-in spend is paid + BYOK + free.
totals
countintegerrequiredSettled requests (or terminal attempts on the attempts basis); not a success count.
rejected_countintegerrequiredFailed or expired requests with no provider dispatch (always 0 on the attempts basis).
errorsintegerrequiredNon-completed requests or attempts, rejections included.
input_tokensintegerrequiredoutput_tokensintegerrequiredcached_input_tokensintegerrequiredreasoning_tokensintegerrequiredpaid_nano_usdstringrequiredCharged credits. Integer nano-USD as a decimal string (1 USD = 1,000,000,000) so JavaScript cannot round it.
byok_nano_usdstringrequiredBring-your-own-key list estimate; never charged. Integer nano-USD as a decimal string (1 USD = 1,000,000,000) so JavaScript cannot round it.
free_nano_usdstringrequiredFree promotional usage at list value; not a credit debit. Integer nano-USD as a decimal string (1 USD = 1,000,000,000) so JavaScript cannot round it.
unknown_usage_countintegerrequiredUsage whose provider accounting is unknown. Nonzero makes the money provisional.
bucketsarray<object>requiredbuckets
startstringrequiredfiguresobjectrequiredExact counters and money legs for one basis. The all-in spend is paid + BYOK + free.
figures
countintegerrequiredSettled requests (or terminal attempts on the attempts basis); not a success count.
rejected_countintegerrequiredFailed or expired requests with no provider dispatch (always 0 on the attempts basis).
errorsintegerrequiredNon-completed requests or attempts, rejections included.
input_tokensintegerrequiredoutput_tokensintegerrequiredcached_input_tokensintegerrequiredreasoning_tokensintegerrequiredpaid_nano_usdstringrequiredCharged credits. Integer nano-USD as a decimal string (1 USD = 1,000,000,000) so JavaScript cannot round it.
byok_nano_usdstringrequiredBring-your-own-key list estimate; never charged. Integer nano-USD as a decimal string (1 USD = 1,000,000,000) so JavaScript cannot round it.
free_nano_usdstringrequiredFree promotional usage at list value; not a credit debit. Integer nano-USD as a decimal string (1 USD = 1,000,000,000) so JavaScript cannot round it.
unknown_usage_countintegerrequiredUsage whose provider accounting is unknown. Nonzero makes the money provisional.
seriesarray<object>requiredseries
valuestring | nullrequiredlabelstringrequiredotherbooleanrequiredfiguresobjectrequiredExact counters and money legs for one basis. The all-in spend is paid + BYOK + free.
figures
countintegerrequiredSettled requests (or terminal attempts on the attempts basis); not a success count.
rejected_countintegerrequiredFailed or expired requests with no provider dispatch (always 0 on the attempts basis).
errorsintegerrequiredNon-completed requests or attempts, rejections included.
input_tokensintegerrequiredoutput_tokensintegerrequiredcached_input_tokensintegerrequiredreasoning_tokensintegerrequiredpaid_nano_usdstringrequiredCharged credits. Integer nano-USD as a decimal string (1 USD = 1,000,000,000) so JavaScript cannot round it.
byok_nano_usdstringrequiredBring-your-own-key list estimate; never charged. Integer nano-USD as a decimal string (1 USD = 1,000,000,000) so JavaScript cannot round it.
free_nano_usdstringrequiredFree promotional usage at list value; not a credit debit. Integer nano-USD as a decimal string (1 USD = 1,000,000,000) so JavaScript cannot round it.
unknown_usage_countintegerrequiredUsage whose provider accounting is unknown. Nonzero makes the money provisional.
cellsarray<object>requiredcells
countintegerrequiredSettled requests (or terminal attempts on the attempts basis); not a success count.
rejected_countintegerrequiredFailed or expired requests with no provider dispatch (always 0 on the attempts basis).
errorsintegerrequiredNon-completed requests or attempts, rejections included.
input_tokensintegerrequiredoutput_tokensintegerrequiredcached_input_tokensintegerrequiredreasoning_tokensintegerrequiredpaid_nano_usdstringrequiredCharged credits. Integer nano-USD as a decimal string (1 USD = 1,000,000,000) so JavaScript cannot round it.
byok_nano_usdstringrequiredBring-your-own-key list estimate; never charged. Integer nano-USD as a decimal string (1 USD = 1,000,000,000) so JavaScript cannot round it.
free_nano_usdstringrequiredFree promotional usage at list value; not a credit debit. Integer nano-USD as a decimal string (1 USD = 1,000,000,000) so JavaScript cannot round it.
unknown_usage_countintegerrequiredUsage whose provider accounting is unknown. Nonzero makes the money provisional.
kindenumrequiredvaluean observed value,missingunattributed calls,otherthe non-selectable remainder.
object
statusanyrequiredreasonanyrequired
400Invalid Spend query, or the query lacks the frozen snapshot this route requires.
Response
errorstringrequiredHuman-readable message.
codestringStable machine reason, when the route defines one (for example
pro_required).actionstringStable remediation action, when the route defines one.
detailsobjectCustomer-safe string facts the caller needs to act (for example a suggested identifier).
401Missing, unknown or revoked API key.
Response
errorstringrequiredHuman-readable message.
codestringStable machine reason, when the route defines one (for example
pro_required).actionstringStable remediation action, when the route defines one.
detailsobjectCustomer-safe string facts the caller needs to act (for example a suggested identifier).
403The key is not a provisioning key (inference keys are refused on every Spend route, reads included), or it is a customer-plan key.
Response
errorstringrequiredHuman-readable message.
codestringStable machine reason, when the route defines one (for example
pro_required).actionstringStable remediation action, when the route defines one.
detailsobjectCustomer-safe string facts the caller needs to act (for example a suggested identifier).
404The org is not the key's own organization (always 404, never 403).
Response
errorstringrequiredHuman-readable message.
codestringStable machine reason, when the route defines one (for example
pro_required).actionstringStable remediation action, when the route defines one.
detailsobjectCustomer-safe string facts the caller needs to act (for example a suggested identifier).
409The snapshot (
as_of+snapshot_id) expired (24 hours) or was invalidated. Refresh and replace every projection together.Response
errorstringrequiredHuman-readable message.
codestringStable machine reason, when the route defines one (for example
pro_required).actionstringStable remediation action, when the route defines one.
detailsobjectCustomer-safe string facts the caller needs to act (for example a suggested identifier).
422Body failed schema validation (
{detail:[...]}), or the report exceeds a work bound (report_too_large,series_too_large,export_too_large).503Reporting is unavailable, initializing, or the bounded read timed out. Not empty data; retry or narrow the range.
Response
errorstringrequiredHuman-readable message.
codestringStable machine reason, when the route defines one (for example
pro_required).actionstringStable remediation action, when the route defines one.
detailsobjectCustomer-safe string facts the caller needs to act (for example a suggested identifier).
Request
curl -X POST https://api.experientiallabs.ai/api/orgs/3f6c2a1e-8b7d-4c2a-9e51-6a0d4b2f7c10/spend/view \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"start": "2026-11-01T00:00:00Z",
"end": "2026-11-08T00:00:00Z",
"time_zone": "UTC",
"scope": "org",
"basis": "requests",
"group_by": "model",
"grain": "day",
"filters": [],
"tags": [],
"sort": "spend",
"direction": "desc",
"offset": 0,
"limit": 50,
"as_of": "2026-11-19T14:02:11.418Z",
"snapshot_id": "c1e7a4d2-5b3f-4e8a-9d61-2f0b7c3a9e45"
}'Response
{
"report": {
"query": {
"start": "2026-11-01T00:00:00Z",
"end": "2026-11-08T00:00:00Z",
"time_zone": "UTC",
"scope": "org",
"basis": "requests",
"group_by": "model",
"grain": "day",
"filters": [],
"tags": [],
"sort": "spend",
"direction": "desc",
"offset": 0,
"limit": 50,
"tag_key": null,
"as_of": "2026-11-19T14:02:11.418Z",
"snapshot_id": "c1e7a4d2-5b3f-4e8a-9d61-2f0b7c3a9e45"
},
"totals": {
"count": 18420,
"rejected_count": 37,
"errors": 212,
"input_tokens": 96214000,
"output_tokens": 8120400,
"cached_input_tokens": 51200000,
"reasoning_tokens": 1840000,
"paid_nano_usd": "41382500000",
"byok_nano_usd": "6120000000",
"free_nano_usd": "850000000",
"unknown_usage_count": 0
},
"buckets": [
{
"start": "2026-11-01T00:00:00Z",
"figures": {
"count": 2610,
"rejected_count": 5,
"errors": 30,
"input_tokens": 13700000,
"output_tokens": 1160000,
"cached_input_tokens": 7300000,
"reasoning_tokens": 262000,
"paid_nano_usd": "5921000000",
"byok_nano_usd": "870000000",
"free_nano_usd": "120000000",
"unknown_usage_count": 0
}
}
],
"groups": [
{
"value": "gpt-6-luna",
"label": "gpt-6-luna",
"figures": {
"count": 11030,
"rejected_count": 20,
"errors": 101,
"input_tokens": 61200000,
"output_tokens": 5102000,
"cached_input_tokens": 38100000,
"reasoning_tokens": 1840000,
"paid_nano_usd": "29880000000",
"byok_nano_usd": "0",
"free_nano_usd": "0",
"unknown_usage_count": 0
}
},
{
"value": "claude-fable-5.1",
"label": "claude-fable-5.1",
"figures": {
"count": 7390,
"rejected_count": 17,
"errors": 111,
"input_tokens": 35014000,
"output_tokens": 3018400,
"cached_input_tokens": 13100000,
"reasoning_tokens": 0,
"paid_nano_usd": "11502500000",
"byok_nano_usd": "6120000000",
"free_nano_usd": "850000000",
"unknown_usage_count": 0
}
}
],
"filter_labels": [],
"group_count": 2,
"next_offset": null,
"coverage": {
"as_of": "2026-11-19T14:02:11.418Z",
"projected_through": "2026-11-08T00:00:00Z",
"complete": true,
"pending_requests": 0,
"includes_pre_admission_rejections": false
}
},
"series": {
"status": "ready",
"data": {
"query": {
"start": "2026-11-01T00:00:00Z",
"end": "2026-11-08T00:00:00Z",
"time_zone": "UTC",
"scope": "org",
"basis": "requests",
"group_by": "model",
"grain": "day",
"filters": [],
"tags": [],
"sort": "spend",
"direction": "desc",
"offset": 0,
"limit": 7,
"tag_key": null,
"as_of": "2026-11-19T14:02:11.418Z",
"snapshot_id": "c1e7a4d2-5b3f-4e8a-9d61-2f0b7c3a9e45"
},
"coverage": {
"as_of": "2026-11-19T14:02:11.418Z",
"projected_through": "2026-11-08T00:00:00Z",
"complete": true,
"pending_requests": 0,
"includes_pre_admission_rejections": false
},
"totals": {
"count": 18420,
"rejected_count": 37,
"errors": 212,
"input_tokens": 96214000,
"output_tokens": 8120400,
"cached_input_tokens": 51200000,
"reasoning_tokens": 1840000,
"paid_nano_usd": "41382500000",
"byok_nano_usd": "6120000000",
"free_nano_usd": "850000000",
"unknown_usage_count": 0
},
"buckets": [
{
"start": "2026-11-01T00:00:00Z",
"figures": {
"count": 2610,
"rejected_count": 5,
"errors": 30,
"input_tokens": 13700000,
"output_tokens": 1160000,
"cached_input_tokens": 7300000,
"reasoning_tokens": 262000,
"paid_nano_usd": "5921000000",
"byok_nano_usd": "870000000",
"free_nano_usd": "120000000",
"unknown_usage_count": 0
}
}
],
"series": [
{
"value": "gpt-6-luna",
"label": "gpt-6-luna",
"other": false,
"kind": "value",
"figures": {
"count": 11030,
"rejected_count": 20,
"errors": 101,
"input_tokens": 61200000,
"output_tokens": 5102000,
"cached_input_tokens": 38100000,
"reasoning_tokens": 1840000,
"paid_nano_usd": "29880000000",
"byok_nano_usd": "0",
"free_nano_usd": "0",
"unknown_usage_count": 0
},
"cells": [
{
"count": 2610,
"rejected_count": 5,
"errors": 30,
"input_tokens": 13700000,
"output_tokens": 1160000,
"cached_input_tokens": 7300000,
"reasoning_tokens": 262000,
"paid_nano_usd": "5921000000",
"byok_nano_usd": "870000000",
"free_nano_usd": "120000000",
"unknown_usage_count": 0
}
]
}
]
}
}
}https://api.experientiallabs.ai/api/orgs/3f6c2a1e-8b7d-4c2a-9e51-6a0d4b2f7c10/spend/view