You may not need this. OpenClaw, Hermes, Claude and Codex agents already report their usage. Grok and Muse agents don’t report it yet. This page is for agents you built yourself, or anything else you want to count.
How it works
Your agent sends a short record after each model call: which model, how many tokens, and what it cost. AgentVault adds them up per model and per agent, and Health shows the totals. Two things to know up front:- It’s self-reported. AgentVault can’t check these numbers. Health labels the total “Estimated model cost” and says “Reported by your agents. Agents that don’t report usage aren’t included in cost.”
- AgentVault doesn’t price anything for you. If you don’t send a cost, the call counts toward calls and tokens at $0.00.
Choose how to send it
- Plugin SDK
- Node.js reporter
- Plain HTTP
If your agent runs on the plugin SDK, it already has a reporter that’s signed in as the agent. Once the agent is It sends a batch every 30 seconds.
ready, call it after each model call:channel.telemetry is null until the agent has connected and knows its hub ID, which is why the example uses ?..Find your agent’s hub ID
Every report names the agent it’s for by its hub ID, a UUID. An API key or device token can only report for its own agent, so use that agent’s hub ID.- With the plugin SDK, it’s
channel.ownHubIdonce the agent is connected. - With an API key, the key’s own agent is the entry with the Agent Name you typed when you made the key. Ask for the same summary Health uses. It lists each agent with its hub ID:
"name": "my-agent" and "hub_id": "…". Pick the one whose name matches your key’s agent. If its hub_id is null, that agent has no hub ID yet, and the key can’t report. Agents that are removed don’t appear.
Check that it worked
1
Send one report
Use any of the three ways above. Wait for the next flush if you used a reporter.
2
Open Health
In the app, open Health (it’s in the sidebar under Reporting on a computer or tablet).
3
Find the model
Under By model, you’ll see a card for the model name you sent, with its calls, tokens and cost. The total at the top, Estimated model cost, now includes it.
The ingest endpoint
Authentication
Any one of these:Authorization: Bearer av_agent_sk_…with an API key, or the same key in anX-Api-KeyheaderAuthorization: Bearer <device-token>with the agent’s own device token- your own session token, when calling from the app
- If the
hub_idisn’t an agent in your account, you get404withHub identity not found. - If it’s another agent in your account, a key or device token gets
403withA device credential can only report telemetry for its own agent.
Body
Each span:
The attributes Health needs
What’s skipped without an error
The endpoint answers201 even when some spans don’t count. It skips quietly when:
- A span has no start or end time. It’s dropped, and the
ingestednumber in the reply doesn’t count it. Check that number. gen_ai.operation.nameisn’t exactly"chat". The span is stored, but it’s not counted on Health.- Both token counts are missing or zero. Same: stored, not counted.
- The cost is negative or not a number. The call counts at $0.00.
- You send the same
traceIdandspanIdagain. Health counts it once. So when you retry a failed send, reuse the same IDs.
- A timestamp sent as a number is read by its size: nanoseconds, microseconds, milliseconds (like JavaScript’s
Date.now()) or seconds since 1970. A string of digits is always read as nanoseconds. A timestamp it can’t read counts as missing, so the span is dropped. - A
traceIdlonger than 32 characters or aspanIdlonger than 16 fails the whole batch.
What the server sees
Telemetry isn’t encrypted for your eyes only. The server stores everything in the report as sent: model names, token counts, costs and any other attributes. Don’t put prompts, replies or secrets in attributes. See the security overview for what else the server can see.If something goes wrong
I get 201 but nothing shows on Health
I get 201 but nothing shows on Health
Check
ingested in the reply. If it’s 0, your spans are missing a start or end time. If it’s 1 or more, check gen_ai.operation.name is exactly "chat" and that at least one token count is above zero. Health shows the last 7 days unless you pick a longer period, counted from when each report arrived.404 Hub identity not found
404 Hub identity not found
The
hub_id isn’t one of your agents. Look it up again with the usage summary call above. A removed agent’s hub ID stops working.403 A device credential can only report telemetry for its own agent
403 A device credential can only report telemetry for its own agent
The
hub_id is a real agent in your account, but not the one your key or token belongs to. Use the hub ID of the key’s own agent. See Find your agent’s hub ID.401 Invalid credentials
401 Invalid credentials
The API key was revoked, expired or rotated, or the token is not valid. Get a new one.
403 Device not found or not active
403 Device not found or not active
The key or token is fine, but its agent is paused or removed. Don’t get a new token — turn Agent active back on, or connect the agent again if it was removed.
The cost shows $0.00
The cost shows $0.00
You didn’t send a cost, or sent one under a name Health doesn’t read. Use
gen_ai.usage.cost_usd, or costUsd with the reporter.The reporter runs but nothing ever shows up
The reporter runs but nothing ever shows up
A reporter drops spans the server rejects, and it doesn’t tell you. A wrong hub ID or a revoked key means every batch is dropped. Check the hub ID belongs to the key’s own agent, and that the key is still active. Then restart.
What’s next
- Read your numbers: Health
- Build the rest of your agent: Plugin SDK