What the sessions created in a period cost and the achievements they earned

GET

/v1/usage/achievements

The sessions GET /v1/usage/summary would count for the same scope, since, until and agent_id, read by the same callers (403 and 404 alike), with the achievements the workspace's achievement rules counted for them (GET /v1/sessions/{id}/achievements). With scope=installation or me, agent_id narrows the sessions to that agent's. session_count and cost_usd are the summary's; each session's cost adds once however many achievements it has.

achievement_count counts the achievements in force whose review state is auto or confirmed; needs_review_count and rejected_count count the others. cost_per_achievement_usd is every session's cost, those without an achievement included, over achievement_count (null with none). judge_cost_usd, judge_calls and judgment_count are the judge's spend on the same sessions, apart from the sessions' cost; judgment_count counts the judgments that called the judge.

type_id and category_id narrow the achievements, never the sessions, their cost or the judge's cost. by_category, by_type and by_rule list the rows with an achievement counted or waiting for review, a category or type under its current name and a rule family once, under its latest version's category, title and version and with every version's achievements; by_agent lists every agent with a session in the period; recent the latest 20 achievements in force, rejected ones included. An achievement of a session the caller may not read (one in another owner, one not shared with the caller, or a workspace-scoped session of an agent whose managing team the caller is outside while agent_outsider_session_visibility is managing_team) is left out of recent, since a conversation's achievement carries its session's title and link; the counts still include it. The period cuts on when each session was created. It changes nothing.

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

Authorization

headerAuthorizationBearer <token>

For servers and scripts: an API key sent as an HTTP bearer token, Bearer <key>. It holds exactly the scopes it was issued with; a key issued before scopes existed holds none. It never needs the CSRF header, and it cannot manage agents, members, teams or API keys. Issue one in the web console under Settings → API keys; each operation names the scope it needs.

Scope: sessions:read

Query Parameters

scope*string

Whose sessions to count. The description says who may read each scope.

Value in"installation""me""agent"

since*|

Start of the period, inclusive: a date (2026-10-01, that day's 00:00 UTC) or a timestamp with an offset, moved to UTC.

until?|

End of the period, exclusive, in the same forms as since. Without it the period ends when the figures are read.

agent_id?string

Counts only the sessions of this agent, any of its releases.

Match

^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

Formatuuid

type_id?string

Counts only the achievements of this achievement type.

Match

^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

Formatuuid

category_id?string

Counts only the achievements of this category.

Match

^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

Formatuuid

Response Body

The figures as of refreshed_at.

application/json

response

scope*string

Value in"installation""me""agent"

period*

refreshed_at*string

Match

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$

Formatdate-time

session_count*integer