Query usage with a JSON filter
Bounded typed alternative to GET /usage for large agent or call selections, with explicit agent and call grouping. POST is used only because the selection can exceed URL limits: this is a read with no effect, safe to retry, needs no Idempotency-Key and counts toward read rate limits. Same workspace authorization, result rows, ordering and cursor rules as the GET form. Body and filter limits are separate from GET: up to 1000 ID values in total and 128 KiB encoded. Results stay paged (limit at most 200); nothing expands transcripts, results or variables. Not a general query language.
Authentication
Create and manage workspace-owned keys through the existing app session routes, outside this public API. Creator and manager identities are audit actors only. Key validity follows workspace policy, expiry and explicit revocation, independently of creator membership. Do not include a workspace-selection header.
Request
Same field names and meaning as the GET /usage query parameters. UTC [start,end), maximum 93 days, default trailing 30 days. Facts are filtered before aggregation.
Same values as the GET group_by filter. [] or omission combines matching facts by component and unit. agent adds agent_id; call adds call_id. No other dimensions.
Opaque cursor from the previous page. It binds the filter and limit: send them unchanged with it; a change is refused with invalid_request. Expires after 24 hours.
Response headers
Response
Open response vocabulary. Preserve unknown values; never assume they mean success.
The resolved UTC [start, end) range used, including defaults (trailing 30 days ending now).