Recent or slowest calls of one tool, and its calls per day
Lists the calls of the tool name whose tool_use event was stored in [since, until), with the scopes, period and agent_id of GET /v1/usage/tools; the period spans at most 366 days. sort=recent (the default) lists the latest occurred_at first, sort=slowest the longest duration_ms first with untimed calls last; ties go to the later event. Read the next page with next_cursor, which is null on the last page; a cursor from the other sort is 400.
session_id and title are null for 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); the call's time, duration, outcome and agent still show. agent is null for a session made without an agent. outcome is unknown while no result is paired or when the result's is_error is not a boolean; duration_ms is null without a paired result or with either time missing, and set even when outcome is unknown. per_day counts the tool's calls on every UTC date the period touches, zeros included. Calls show up within one reconciler pass of being stored. It changes nothing.
Scope: sessions:read (API key or cookie session).
AuthorizationBearer <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
name*stringThe tool's name as its tool_use event recorded it.
1 <= length <= 512scope*stringWhose sessions to count. The description says who may read each scope.
"installation""me"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?stringCounts only the sessions of this agent, any of its releases.
^([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)$uuidsort?stringrecent lists the latest call first, slowest the longest first.
"recent""recent""slowest"limit?integerHow many items a page holds at most.
1 <= value <= 10020cursor?stringThe next_cursor of the page before; omit it for the first page.
1 <= lengthOne page of the tool's calls.
application/json- response
calls*array<>items <= 100next_cursor*|nullper_day*array<>curl -X GET 'https://example.com/v1/usage/tools/string/calls?scope=installation&since=2019-08-24'{ "calls": [ { "session_id": "0f8b6a52-3d1e-4c7a-9b2f-5e6d7c8a9b01", "title": "Fix the flaky login test", "agent": "Reviewer", "occurred_at": "2026-10-24T09:14:03.120Z", "duration_ms": 3120, "outcome": "ok" }, { "session_id": null, "title": null, "agent": null, "occurred_at": "2026-10-24T09:12:41.004Z", "duration_ms": null, "outcome": "unknown" } ], "next_cursor": "eyJzb3J0IjoicmVjZW50IiwiYXQiOiIyMDI2LTEwLTI0IDA5OjEyOjQxLjAwNCswMCIsImlkIjo0MjEsIm9yZCI6MX0", "per_day": [ { "date": "2026-10-23", "calls": 0 }, { "date": "2026-10-24", "calls": 2 } ]}