Skip to main content
After this page, your agent’s model calls, token counts and cost will show on Health, next to your other agents.
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.
Messages sent, last seen and online time on Health don’t come from telemetry. The server records those itself.

Choose how to send it

If your agent runs on the plugin SDK, it already has a reporter that’s signed in as the agent. Once the agent is ready, call it after each model call:
It sends a batch every 30 seconds. 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.ownHubId once 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:
You’ll see one line pair per agent, like "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 an X-Api-Key header
  • Authorization: Bearer <device-token> with the agent’s own device token
  • your own session token, when calling from the app
An API key or device token may only report for its own agent. Your own session token, from the app, may report for any agent in your account.
  • If the hub_id isn’t an agent in your account, you get 404 with Hub identity not found.
  • If it’s another agent in your account, a key or device token gets 403 with A device credential can only report telemetry for its own agent.

Body

Each span:

The attributes Health needs

This endpoint takes the AgentVault body above, not the standard OpenTelemetry resourceSpans format. An off-the-shelf OpenTelemetry exporter pointed at it won’t work as-is. Send the hub_id and spans shape shown here.

What’s skipped without an error

The endpoint answers 201 even when some spans don’t count. It skips quietly when:
  • A span has no start or end time. It’s dropped, and the ingested number in the reply doesn’t count it. Check that number.
  • gen_ai.operation.name isn’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 traceId and spanId again. Health counts it once. So when you retry a failed send, reuse the same IDs.
And a few that do return errors:
  • 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 traceId longer than 32 characters or a spanId longer 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

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.
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.
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.
The API key was revoked, expired or rotated, or the token is not valid. Get a new one.
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.
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.
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