komrad

get_token_use

Read what each agent spent in tokens since midnight, with its conversation size and compactions, every agent's running totals, and the tools whose results filled the conversations.

read-onlyidempotentCLI onlySystem

Calling it#

curl -X POST http://127.0.0.1:8787/komrad.system.v1.SystemService/GetTokenUse \
  -H 'Content-Type: application/json' \
  -d '{}'

Request#

GetTokenUseRequest#

FieldTypeDescription
agent_iduuid

The agent whose running totals, conversation sizes and tools to read alongside every agent's. Unset reads every agent's alone.

Response#

GetTokenUseResponse#

FieldTypeDescription
tokensTokenCounts

The tokens every agent spent since midnight.

agentsAgentTokenUse[]

Every agent that made a model call since midnight, the most tokens first.

totalsTokenTotal[]

Every agent's running totals every five minutes since midnight, the last at the time of the read.

toolsToolTokenUse[]

Every tool every agent called since midnight, the most tokens first.

agent_totalsTokenTotal[]

The named agent's running totals every five minutes since midnight. Empty when the request names no agent.

agent_conversationConversationSize[]

The named agent's conversation size at each model call since midnight, oldest first. Empty when the request names no agent.

agent_toolsToolTokenUse[]

Every tool the named agent called since midnight, the most tokens first. Empty when the request names no agent.

Types#

TokenCounts#

TokenCounts is tokens split by what the model did with them.

FieldTypeDescription
inputint64

The prompt tokens the cache did not serve.

cache_readint64

The prompt tokens the cache served.

cache_writeint64

The prompt tokens the model wrote to the cache.

outputint64

The tokens the model sent back, reasoning included.

AgentTokenUse#

AgentTokenUse is what one agent spent in tokens today.

FieldTypeDescription
agent_idstring

The agent's id.

namestring

The agent's name when it made its latest model call.

harnessstring

The harness the agent runs on, such as claude or codex.

cli_versionstring

The version of the CLI that made the agent's latest model call.

modelstring

The model of the agent's latest model call.

effortstring

The effort of the agent's latest model call. Empty when the CLI reported none.

tokensTokenCounts

The tokens the agent spent today.

model_callsint64

How many model calls the agent made today.

conversation_tokensint64

The agent's conversation size: the input, cache read and cache write tokens of its latest model call that counts toward its conversation.

compactionstimestamp[]

When the agent's conversation shrank to under half its size today, as it does when the CLI compacts it, oldest first.

latest_attimestamp

When the agent made its latest model call.

TokenTotal#

TokenTotal is the tokens model calls sent and got back from midnight up to a time.

FieldTypeDescription
attimestamp

The time the total runs up to.

inputint64

The input, cache read and cache write tokens of every model call up to the time.

outputint64

The output tokens of every model call up to the time.

ToolTokenUse#

ToolTokenUse is what one tool's calls sent back today, which every later model call in the conversation sends again.

FieldTypeDescription
toolstring

The tool, as the CLI names it.

tool_callsint64

How many times the tool was called.

result_tokensint64

About how many tokens the calls sent back.

commandsCommandTokenUse[]

The shell tool's calls split by the command they ran, the most tokens first. Empty for any other tool.

ConversationSize#

ConversationSize is an agent's conversation size at one model call.

FieldTypeDescription
attimestamp

When the agent made the model call.

tokensint64

The input, cache read and cache write tokens of the model call.

CommandTokenUse#

CommandTokenUse is what the shell tool's calls that ran one command sent back today.

FieldTypeDescription
commandstring

The program and subcommand the calls ran, such as go test or git diff.

tool_callsint64

How many tool calls ran the command.

result_tokensint64

About how many tokens the calls sent back.