Skip to main content
POST
Get tool usage and prompt cache census

Authorizations

x-access-token
string
header
required

JWT token passed in x-access-token header

Body

application/json
view
enum<string>
default:tools

tools - calls, turns, successes, MCP calls, distinct users and twins per tool and lane. turns - how many turns make 0, 1, 2, 3, 4 or 5+ tool calls per lane, with token sums. models - turns, turns with tools, cold turns, cache reads and writes per model and lane. conversations - conversation size buckets, tool use, first tool use, and distinct tools per tool-using conversation (text lanes only). The model, tier and modeSource filters select turns before they are grouped, so a conversation that mixes models or modes is measured over its matching turns only. limits - how often each spending limit acted or, while it is only measured, would have acted. Events per 1,000 turns by kind, mode, lane and tier, per Digital Twin, and what happened next - answered, thumbs down against the twin's own rate, asked again within 10 minutes (measured on the 300 newest events that have a saved turn), paused plan tasks continued and the median minutes to Continue. API (chat) and channel turns save no history row, so their events carry no rate. taskCost - credits per completed single answer, conducted turn and plan run (p50, p90, p99, max) by tier and per Digital Twin. coverage - per lane and Digital Twin, the smallest set of tool definitions that covers the given share of tool turns (greedy by turns per definition byte); the basis of the always-loaded set on the Claude lanes. searches - per tool and lane, the turns in which Claude's tool search surfaced the tool, with distinct users and twins, and per-lane totals.

Available options:
tools,
turns,
models,
conversations,
limits,
taskCost,
coverage,
searches
lane
enum<string>
default:all

Restrict to one lane. The conversations view does not accept convo. The workers lane exists only in the tools view. In the tools view, all returns the turn-level rows and the workers rows. The limits and taskCost views do not take it; coverage and searches take all, qanda, convo or agentic.

Available options:
all,
qanda,
convo,
agentic,
workers
model
string

Exact conversation model name to restrict to. The limits, taskCost, coverage and searches views do not take it.

Maximum string length: 200
tier
enum<string>

Count only the turns that declared this mode. auto - nothing picked a mode (classic users without the mode control, API traffic, and sends left on Auto). basic - one model chats and runs tools itself, with no background worker. advanced, expert, mythical - conducted modes. Applies to every view. Avatar embed sessions record no mode and are left out.

Available options:
auto,
basic,
advanced,
expert,
mythical
modeSource
enum<string>

Count only the turns whose mode came from here. request - the send named a mode, from either interface. membership - the send named none and the server applied the member's saved mode. default - nothing named a mode. Applies to every view. It does not tell the classic interface from the new one. The limits view does not take it.

Available options:
request,
membership,
default
kind
enum<string>

Limits view only - count only this kind of event. answer_limit - an answer reached its limit. task_extend, task_pause, task_resume - a task was extended once, paused at its limit, continued. balance_shorten, cap_shorten - a turn was shortened by a low balance or a credit quota. hourly_limit - a person passed the hourly limit through the API or channels.

Available options:
answer_limit,
task_extend,
task_pause,
task_resume,
balance_shorten,
cap_shorten,
hourly_limit
splitByTier
boolean
default:false

Tools and turns views only - return one row per tier, with a tier key on every row. Any other view answers 400. A request without it returns exactly the rows it returned before this parameter existed. In the tools view, top then counts tool by lane by tier rows, so the same top truncates sooner (truncated says so) - narrow the lane or raise top.

institution
string

Space-separated institution IDs to filter (institution is the API word for a Digital Twin). Must be a string - any other type is rejected.

account
string

Space-separated account IDs to filter. Must be a string.

daterange
string<date>[]

Start and end day, inclusive, in UTC. At most 31 days. Defaults to the last 7 days.

Required array length: 2 elements
top
integer
default:200

Maximum rows for the tools view, ordered by calls

Required range: 1 <= x <= 500
target
integer
default:90

coverage view only - the share of tool turns the chosen set must cover.

Required range: 50 <= x <= 100

Response

Census for the requested view

success
boolean
data
object