/api/orgs/{org_id}/spend/buildsPrepare a Spend report
Prepares an exact frozen aggregate for large ranges. Free: no usage intelligence charge. An unpinned query freezes its own snapshot; poll GET /builds/{build_id} until completed. 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
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.
Responses
200OK
Response
idstringrequiredstatusenumrequiredCurrently returned:
running,completed,failedorexpired.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.
created_atstringrequiredupdated_atstringrequiredexpires_atstringrequiredprogressobjectrequiredCommitted checkpoint counters, not a percent complete.
progress
processed_factsintegerrequiredprocessed_sourcesintegerrequiredphaseenumrequired
error_codestring | nullrequired
400Invalid Spend query (bad filter value, a future
as_of, a personalscope: selffrom a key, or a missing snapshot where one is required).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).429Report preparation is at capacity. Carries
Retry-After: 1.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).
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/builds \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"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
}
}'Response
{
"id": "8d2f1c6a-3e4b-4a7d-b9e0-5c1f2a7d8e30",
"status": "running",
"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"
},
"created_at": "2026-11-19T14:02:11.420Z",
"updated_at": "2026-11-19T14:02:12.031Z",
"expires_at": "2026-11-20T14:02:11.420Z",
"progress": {
"processed_facts": 0,
"processed_sources": 0,
"phase": "coverage"
},
"error_code": null
}https://api.experientiallabs.ai/api/orgs/3f6c2a1e-8b7d-4c2a-9e51-6a0d4b2f7c10/spend/builds