hm_tokens

hm_tokens reports how many tokens one agent turn used, which model and tool it ran on, and what kind of work it was. HyperMemory turns these reports into the token usage views in your dashboard and, for organizations, across every member.

Agents call it once per turn, during end-of-turn finalization. The HyperMemory plugins do this for you through their memory-writer agent.

Parameters

Parameter	Type	Description
`session_id`	string	Required. The conversation’s id.
`turn_sequence`	integer	Required. The turn’s number in the session, starting at 1. Together with `session_id` it makes a report unique; a repeated report is flagged as a duplicate, not counted twice.
`ai_tool`	string	Required. The client, e.g. `claude_code`, `codex`, `cursor`, `claude_desktop`, `chatgpt`.
`provider`	string	Required. The model provider, e.g. `anthropic`, `openai`, `openrouter`.
`model`	string	Required. The exact model id.
`measurement_quality`	string	Required. How the counts were obtained — see below.
`segments`	array	Required. What the turn was spent on — see below.
`input_tokens`, `output_tokens`, `total_tokens`	integer	Token counts.
`cache_tokens`	integer	Cached prompt tokens.
`cache_accounting`	`"separate"` \| `"included_in_input"`	Whether `cache_tokens` are counted inside `input_tokens`. Default `separate`.
`reasoning_tokens`	integer	Reasoning tokens, when the model reports them.
`billing_account`	string	What the call was billed to — see below.
`estimation_bias`	`low` \| `neutral` \| `high`	Only with `self_estimated`: whether the estimate is likely low, about right, or high.
`uncertainty_percentage`	integer	Only with `self_estimated`: how far off it may be (0–100). Include only when you can justify it.
`cost_usd`, `cost_quality`	string	Cost, if the client knows it. Omit both when unknown.
`ai_account_id`, `provider_event_id`	string	Optional identifiers.

`measurement_quality`

Value	Use when
`client_exact`	The client exposes exact usage (API hooks, Codex app-server, SDKs).
`self_estimated`	The agent estimates its own usage (Claude Desktop, ChatGPT and other consumer apps). Include `estimation_bias`.
`provider_actual`	Reserved for usage HyperMemory imports from a provider account. Agents never send it.
`unavailable`	The client can’t measure or estimate usage. Send no token counts or cost.

`segments`

Each segment is { "category": ..., "weight": 1–100 }. Categories must be unique and weights must total exactly 100. Make the turn’s real work the largest share.

Category
`coding`	`writing`	`research`
`reasoning`	`planning`	`design`
`doc_processing`	`calculations`	`automation`
`productivity`	`chatting`	`personal`
`memory`	`context`	`unmatched`

Use memory only for HyperMemory’s own overhead and context only for reading. Deployment, testing and debugging count as coding.

`billing_account`

Value	Meaning
`subscription`	A plan: Claude Pro/Max, ChatGPT Plus/Pro, or Codex/Claude Code on a plan.
`api_key:<id>`	An API key id (OpenAI `key_...`, Anthropic `apikey_...`, an OpenRouter key hash).
`project:<id>`	An OpenAI project.
`workspace:<id>`	An Anthropic workspace.

When an administrator connects that provider account, HyperMemory imports the provider’s own usage and replaces the reports that declared the same billing account. Reports without a billing account stay counted beside the import — so totals are exact only when agents declare it.

Response

Field	Description
`event_id`	The stored report’s id.
`duplicate`	`true` when this `session_id` + `turn_sequence` was already reported.
`provider_verified`	`true` once the report has been matched by usage imported from the provider.

The server records the time it received the report.

Example

{
  "session_id": "b2fc5ddb-3818-4894-9d1d-849f890c9926",
  "turn_sequence": 3,
  "ai_tool": "claude_code",
  "provider": "anthropic",
  "model": "claude-opus-5-5",
  "measurement_quality": "self_estimated",
  "input_tokens": 82000,
  "output_tokens": 3100,
  "total_tokens": 85100,
  "estimation_bias": "neutral",
  "billing_account": "subscription",
  "segments": [
    { "category": "coding", "weight": 70 },
    { "category": "research", "weight": 20 },
    { "category": "memory", "weight": 10 }
  ]
}

If validation fails, the error says which field is wrong. Correct the payload once; don’t retry it unchanged.

Equivalents

curl -X POST https://api.hypermemory.io/api/v1/memory/hm_tokens \
  -H "Authorization: Bearer $HYPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d @turn.json