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.

Available options:
tools,
turns,
models,
conversations
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.

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

Exact conversation model name to restrict to

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.

Available options:
request,
membership,
default
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

Response

Census for the requested view

success
boolean
data
object