Report consumption over a period
Token and cost consumption between two instants, over the whole home, grouped by the dimension you ask for. Every member of the organisation reads the same total, including the rounds of conversations their owners marked private: what the organisation spends on its own tools is not the content of a conversation, so no clause narrows these rows the way the search and file reads on this tag are narrowed. The parts add up to the whole.
Marking a conversation private hides its words, not its money. Its rounds are in this report, under their owner’s line, for every member. A person choosing that mark is entitled to know exactly what it does and does not cover.
A person is named by the opaque subject the identity provider issued, never an email address and never a display name.
Grouping by repository is the one dimension whose key could be content: a repository name belongs to the conversation that ran in it. So every conversation the caller may not read lands in ONE group keyed private, which is a real line with real money in it and no name. Nothing is dropped, so the parts still sum to the whole. Ids are not content, so the conversation and person dimensions carry their real keys.
It reports the usage rows this home still holds. Those rows ride their conversation, so purging a conversation takes its cost out of every total computed afterwards. Warming charges and schedule-fire amounts are separate ledgers and are not in this figure.
PAGING IS OPT-IN ON THIS OPERATION, which is the one place the shared limit parameter’s own default of 25 does not apply. Send neither cursor nor limit and the answer carries every group and no nextCursor — the whole period, as this report has always answered. Name either one and paging applies, with 25 as the default size. The exception exists because a total silently cut at a page is a bill that reads as complete and is not.
Authorizations
Enforced on every transport, with no exempt operation. A person's request — over the default local unix socket exactly as over a TCP listener — must carry a JWT issued by the configured identity provider, which the host verifies itself against that issuer's key set: signature, issuer, expiry, and the person and organisation it names. Requests without a valid one receive 401 NRY-0011. The socket's file permissions are transport and are not an authorisation.
Query Parameters
Start of the period, inclusive.
End of the period, exclusive.
Grouping dimension. model is the default and the answer an older client that sends none keeps getting. day is the UTC day the round was stamped with, which is the store's own clock and not the caller's. repository and person are read off the conversation each round ran in. A dimension this version does not serve is refused naming itself.
model, day, repository, conversation, person Opaque pagination cursor from a previous page's nextCursor or prevCursor.
1024Maximum items per page.
1 <= x <= 100Response
The usage report.
Consumption over a period, broken down by the requested dimension. One page of it: the rows are ordered by their own group key ascending — the model name, the UTC day, the repository path, the conversation id or the person's subject, whichever was asked for — and the withheld private group, which has no key of its own, comes first. A key is unique per group by construction, so there is no tie to break and the cursor is simply the last key served.
The dimension these rows are grouped by, echoed from the request.
model, day, repository, conversation, person Pass as cursor for the next page, with the same groupBy. A cursor issued for one grouping is refused by another rather than re-interpreted against a key it does not name. Absent on the last page.