Cost, tokens and run time of the sessions created in a period

Adds up the sessions created in [since, until): how many, their estimated provider cost, their tokens, and how long their turns ran. since and until take a date (2026-10-01, that day's 00:00 UTC) or a timestamp with an offset, which is moved to UTC; without until the period ends when the figures are read, so since must then be in the past.

• scope=me: the sessions the caller started. A personal API key counts as the person who created it; a key nobody created counts the sessions it started itself. Sessions shared with the caller are not added. A key bound to an agent gets 403, as it does from GET /v1/sessions.
• scope=installation: every session of every owner. Only the workspace owner, signed in, reads it: any other member and every API key get 403.
• scope=agent with agent_id: the sessions started from any release of that agent, whoever started them. The workspace's owner and admins and the agent's admins read it; anyone else, and every API key, gets 403, and an agent of another workspace, or none, is 404 for everyone. agent_id is required with it and refused with any other scope, and group_by is refused with it.

cost_usd is the sum of cost.amount_usd from GET /v1/sessions/{id}/usage over the same sessions: an estimate, not a bill. cost_complete: false means one of them has a turn still open or one that ended without reporting its cost, so the true total is unknown. run_seconds is wall-clock turn time, waiting for an answer included; an open turn counts up to refreshed_at. Sessions from before tokens were metered count 0 tokens.

group_by=agent, group_by=user or group_by=profile adds groups: the same sessions, each once, under its agent, the user holding it or the session's current profile (sessions.profile_id; a session that changed profile counts whole under the one it has now), largest cost first, read in the same statement as the totals. The groups' session_count, cost_usd and run_seconds add up to the totals (run_seconds is the floor of the running total minus the floor of the one before it, so two groups of 1.5 seconds read 1 and 2), and cost_complete is false when any group's is. id is the agent id, user id or profile id; it is null for sessions without an agent or a profile, or started by a key no person created. name is the agent's name, the user's display name (never an email) or, as profiles have no display name, the profile id; under scope=me a user other than the caller is null. Without group_by there is no groups. It changes nothing.

Scope: sessions:read (API key or cookie session).