# 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-only · idempotent · CLI only · [System](https://komrad.dev/latest/api/system.md)

## Calling it

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

```bash
komrad rpc get-token-use
```

## Request

### GetTokenUseRequest

| Field | Type | Description |
| --- | --- | --- |
| [`agent_id`](https://komrad.dev/latest/api/system/get-token-use.md#komrad-system-v1-GetTokenUseRequest-agent_id) | uuid | The agent whose running totals, conversation sizes and tools to read alongside every agent's. Unset reads every agent's alone. |

## Response

### GetTokenUseResponse

| Field | Type | Description |
| --- | --- | --- |
| [`tokens`](https://komrad.dev/latest/api/system/get-token-use.md#komrad-system-v1-GetTokenUseResponse-tokens) | [TokenCounts](https://komrad.dev/latest/api/system/get-token-use.md#komrad-system-v1-TokenCounts) | The tokens every agent spent since midnight. |
| [`agents`](https://komrad.dev/latest/api/system/get-token-use.md#komrad-system-v1-GetTokenUseResponse-agents) | [AgentTokenUse\[\]](https://komrad.dev/latest/api/system/get-token-use.md#komrad-system-v1-AgentTokenUse) | Every agent that made a model call since midnight, the most tokens first. |
| [`totals`](https://komrad.dev/latest/api/system/get-token-use.md#komrad-system-v1-GetTokenUseResponse-totals) | [TokenTotal\[\]](https://komrad.dev/latest/api/system/get-token-use.md#komrad-system-v1-TokenTotal) | Every agent's running totals every five minutes since midnight, the last at the time of the read. |
| [`tools`](https://komrad.dev/latest/api/system/get-token-use.md#komrad-system-v1-GetTokenUseResponse-tools) | [ToolTokenUse\[\]](https://komrad.dev/latest/api/system/get-token-use.md#komrad-system-v1-ToolTokenUse) | Every tool every agent called since midnight, the most tokens first. |
| [`agent_totals`](https://komrad.dev/latest/api/system/get-token-use.md#komrad-system-v1-GetTokenUseResponse-agent_totals) | [TokenTotal\[\]](https://komrad.dev/latest/api/system/get-token-use.md#komrad-system-v1-TokenTotal) | The named agent's running totals every five minutes since midnight. Empty when the request names no agent. |
| [`agent_conversation`](https://komrad.dev/latest/api/system/get-token-use.md#komrad-system-v1-GetTokenUseResponse-agent_conversation) | [ConversationSize\[\]](https://komrad.dev/latest/api/system/get-token-use.md#komrad-system-v1-ConversationSize) | The named agent's conversation size at each model call since midnight, oldest first. Empty when the request names no agent. |
| [`agent_tools`](https://komrad.dev/latest/api/system/get-token-use.md#komrad-system-v1-GetTokenUseResponse-agent_tools) | [ToolTokenUse\[\]](https://komrad.dev/latest/api/system/get-token-use.md#komrad-system-v1-ToolTokenUse) | 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.

| Field | Type | Description |
| --- | --- | --- |
| [`input`](https://komrad.dev/latest/api/system/get-token-use.md#komrad-system-v1-TokenCounts-input) | int64 | The prompt tokens the cache did not serve. |
| [`cache_read`](https://komrad.dev/latest/api/system/get-token-use.md#komrad-system-v1-TokenCounts-cache_read) | int64 | The prompt tokens the cache served. |
| [`cache_write`](https://komrad.dev/latest/api/system/get-token-use.md#komrad-system-v1-TokenCounts-cache_write) | int64 | The prompt tokens the model wrote to the cache. |
| [`output`](https://komrad.dev/latest/api/system/get-token-use.md#komrad-system-v1-TokenCounts-output) | int64 | The tokens the model sent back, reasoning included. |

### AgentTokenUse

AgentTokenUse is what one agent spent in tokens today.

| Field | Type | Description |
| --- | --- | --- |
| [`agent_id`](https://komrad.dev/latest/api/system/get-token-use.md#komrad-system-v1-AgentTokenUse-agent_id) | string | The agent's id. |
| [`name`](https://komrad.dev/latest/api/system/get-token-use.md#komrad-system-v1-AgentTokenUse-name) | string | The agent's name when it made its latest model call. |
| [`harness`](https://komrad.dev/latest/api/system/get-token-use.md#komrad-system-v1-AgentTokenUse-harness) | string | The harness the agent runs on, such as `claude` or `codex`. |
| [`cli_version`](https://komrad.dev/latest/api/system/get-token-use.md#komrad-system-v1-AgentTokenUse-cli_version) | string | The version of the CLI that made the agent's latest model call. |
| [`model`](https://komrad.dev/latest/api/system/get-token-use.md#komrad-system-v1-AgentTokenUse-model) | string | The model of the agent's latest model call. |
| [`effort`](https://komrad.dev/latest/api/system/get-token-use.md#komrad-system-v1-AgentTokenUse-effort) | string | The effort of the agent's latest model call. Empty when the CLI reported none. |
| [`tokens`](https://komrad.dev/latest/api/system/get-token-use.md#komrad-system-v1-AgentTokenUse-tokens) | [TokenCounts](https://komrad.dev/latest/api/system/get-token-use.md#komrad-system-v1-TokenCounts) | The tokens the agent spent today. |
| [`model_calls`](https://komrad.dev/latest/api/system/get-token-use.md#komrad-system-v1-AgentTokenUse-model_calls) | int64 | How many model calls the agent made today. |
| [`conversation_tokens`](https://komrad.dev/latest/api/system/get-token-use.md#komrad-system-v1-AgentTokenUse-conversation_tokens) | int64 | The agent's conversation size: the input, cache read and cache write tokens of its latest model call that counts toward its conversation. |
| [`compactions`](https://komrad.dev/latest/api/system/get-token-use.md#komrad-system-v1-AgentTokenUse-compactions) | timestamp\[\] | When the agent's conversation shrank to under half its size today, as it does when the CLI compacts it, oldest first. |
| [`latest_at`](https://komrad.dev/latest/api/system/get-token-use.md#komrad-system-v1-AgentTokenUse-latest_at) | timestamp | 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.

| Field | Type | Description |
| --- | --- | --- |
| [`at`](https://komrad.dev/latest/api/system/get-token-use.md#komrad-system-v1-TokenTotal-at) | timestamp | The time the total runs up to. |
| [`input`](https://komrad.dev/latest/api/system/get-token-use.md#komrad-system-v1-TokenTotal-input) | int64 | The input, cache read and cache write tokens of every model call up to the time. |
| [`output`](https://komrad.dev/latest/api/system/get-token-use.md#komrad-system-v1-TokenTotal-output) | int64 | 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.

| Field | Type | Description |
| --- | --- | --- |
| [`tool`](https://komrad.dev/latest/api/system/get-token-use.md#komrad-system-v1-ToolTokenUse-tool) | string | The tool, as the CLI names it. |
| [`tool_calls`](https://komrad.dev/latest/api/system/get-token-use.md#komrad-system-v1-ToolTokenUse-tool_calls) | int64 | How many times the tool was called. |
| [`result_tokens`](https://komrad.dev/latest/api/system/get-token-use.md#komrad-system-v1-ToolTokenUse-result_tokens) | int64 | About how many tokens the calls sent back. |
| [`commands`](https://komrad.dev/latest/api/system/get-token-use.md#komrad-system-v1-ToolTokenUse-commands) | [CommandTokenUse\[\]](https://komrad.dev/latest/api/system/get-token-use.md#komrad-system-v1-CommandTokenUse) | 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.

| Field | Type | Description |
| --- | --- | --- |
| [`at`](https://komrad.dev/latest/api/system/get-token-use.md#komrad-system-v1-ConversationSize-at) | timestamp | When the agent made the model call. |
| [`tokens`](https://komrad.dev/latest/api/system/get-token-use.md#komrad-system-v1-ConversationSize-tokens) | int64 | 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.

| Field | Type | Description |
| --- | --- | --- |
| [`command`](https://komrad.dev/latest/api/system/get-token-use.md#komrad-system-v1-CommandTokenUse-command) | string | The program and subcommand the calls ran, such as `go test` or `git diff`. |
| [`tool_calls`](https://komrad.dev/latest/api/system/get-token-use.md#komrad-system-v1-CommandTokenUse-tool_calls) | int64 | How many tool calls ran the command. |
| [`result_tokens`](https://komrad.dev/latest/api/system/get-token-use.md#komrad-system-v1-CommandTokenUse-result_tokens) | int64 | About how many tokens the calls sent back. |
