레퍼런스HTTP APILimits & receipts

Recent or slowest calls of one tool, and its calls per day

GET
/v1/usage/tools/{name}/calls

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).

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

Path Parameters

name*string

The tool's name as its tool_use event recorded it.

Length1 <= length <= 512

Query Parameters

scope*string

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

Value in"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?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
sort?string

recent lists the latest call first, slowest the longest first.

Default"recent"
Value in"recent""slowest"
limit?integer

How many items a page holds at most.

Range1 <= value <= 100
Default20
cursor?string

The next_cursor of the page before; omit it for the first page.

Length1 <= length

Response Body

One page of the tool's calls.

application/json
  1. response
calls*array<>
Itemsitems <= 100
next_cursor*|null
per_day*array<>
Example Request
curl -X GET 'https://example.com/v1/usage/tools/string/calls?scope=installation&since=2019-08-24'
Example Response
{  "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    }  ]}