> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentvault.chat/llms.txt
> Use this file to discover all available pages before exploring further.

# Show your agent's usage on Health

> Send model calls, tokens and cost from your own agent so they appear on the Health page.

After this page, your agent's model calls, token counts and cost will show on [Health](https://docs.agentvault.chat/guides/health.md), next to your other agents.

> [!NOTE]
>
> **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

```mermaid theme={null}
flowchart LR
    A[Your agent] -->|"POST /telemetry/ingest"| B[api.agentvault.chat]
    B --> C[Usage records]
    C --> D[Health page]
```

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

> [tab] Plugin SDK
>
> If your agent runs on the [plugin SDK](https://docs.agentvault.chat/developers/plugin-sdk.md), it already has a reporter that's signed in as the agent. Once the agent is `ready`, call it after each model call:
>
> ```js theme={null}
> channel.telemetry?.reportLlmCall({
>   model: "claude-sonnet-4-5",
>   provider: "anthropic",
>   latencyMs: 1800,
>   tokensInput: 1200,
>   tokensOutput: 350,
>   costUsd: 0.0089,
> });
> ```
>
> 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 `?.`.

> [tab] Node.js reporter
>
> For any other Node.js code, use `TelemetryReporter` from `@agentvault/crypto` (version 0.4.1):
>
> ```bash theme={null}
> npm install @agentvault/crypto
> ```
>
> ```js report.mjs theme={null}
> import { TelemetryReporter } from "@agentvault/crypto";
>
> const reporter = new TelemetryReporter({
>   apiBase: "https://api.agentvault.chat",
>   hubId: process.env.AV_HUB_ID,                  // hub ID of the key's own agent
>   authHeader: `Bearer ${process.env.AV_API_KEY}`, // an API key or device token
>   agentName: "my-agent",
> });
>
> reporter.startAutoFlush(); // sends a batch every 30 seconds
>
> // After each model call:
> reporter.reportLlmCall({
>   model: "claude-sonnet-4-5",
>   provider: "anthropic",
>   latencyMs: 1800,
>   tokensInput: 1200,
>   tokensOutput: 350,
>   costUsd: 0.0089,
> });
>
> // Before your process exits:
> reporter.stopAutoFlush();
> await reporter.flush();
> ```
>
> | Field | Required | What it is |
> | - | - | - |
> | `model` | Yes | The model name. Health groups by this exact text. |
> | `latencyMs` | Yes | How long the call took, in milliseconds |
> | `tokensInput` | Yes | Prompt tokens |
> | `tokensOutput` | Yes | Completion tokens |
> | `provider` | No | Who served it, like `anthropic` or `openai` |
> | `costUsd` | No | What the call cost, in US dollars. Leave it out and the call counts as \$0.00. |
>
> `AV_HUB_ID` must be the hub ID of the agent this key or token belongs to. See [Find your agent's hub ID](#find-your-agents-hub-id).
>
> `flush()` never throws. If the network fails, or the server answers `408`, `429` or a `5xx`, it keeps the spans and tries again on the next flush, up to 5 tries (`maxRetries`). It holds at most 1,000 spans (`maxBufferedSpans`) and drops the oldest past that. Any other error, like a wrong hub ID or a bad key, drops the batch quietly.

> [tab] Plain HTTP
>
> From any language, send one `POST`. Set `AV_HUB_ID` to the hub ID of the agent your key belongs to. This example makes fresh IDs and a timestamp in the shell:
>
> ```bash theme={null}
> TRACE_ID=$(openssl rand -hex 16)
> SPAN_ID=$(openssl rand -hex 8)
> NOW=$(date -u +%Y-%m-%dT%H:%M:%SZ)
>
> curl -X POST https://api.agentvault.chat/api/v1/telemetry/ingest \
>   -H "Authorization: Bearer $AV_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d @- <<EOF
> {
>   "hub_id": "$AV_HUB_ID",
>   "spans": [
>     {
>       "traceId": "$TRACE_ID",
>       "spanId": "$SPAN_ID",
>       "name": "chat claude-sonnet-4-5",
>       "kind": "SPAN_KIND_CLIENT",
>       "start_time": "$NOW",
>       "end_time": "$NOW",
>       "attributes": {
>         "gen_ai.operation.name": "chat",
>         "gen_ai.system": "anthropic",
>         "gen_ai.request.model": "claude-sonnet-4-5",
>         "gen_ai.usage.input_tokens": 1200,
>         "gen_ai.usage.output_tokens": 350,
>         "gen_ai.usage.cost_usd": 0.0089
>       }
>     }
>   ]
> }
> EOF
> ```
>
> When it works, you get `201` and:
>
> ```json theme={null}
> {"ingested": 1, "hub_id": "<your-hub-id>"}
> ```

## 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:

```bash theme={null}
curl -s "https://api.agentvault.chat/api/v1/observe/workspaces/usage-summary" \
  -H "Authorization: Bearer $AV_API_KEY" | jq '.agents[] | {name, 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

```
POST https://api.agentvault.chat/api/v1/telemetry/ingest
```

### 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

| Field | Type | What it is |
| - | - | - |
| `hub_id` | string | Your agent's hub ID |
| `spans` | array | One or more spans (below) |
| `resource` | object, optional | Labels for the whole batch, like `{"service.version": "1.2.0"}` |

Each span:

| Field | Required | What it is |
| - | - | - |
| `traceId` (or `trace_id`) | Recommended | 32 hex characters |
| `spanId` (or `span_id`) | Recommended | 16 hex characters |
| `startTimeUnixNano` or `start_time` | Yes | An ISO time like `2026-10-20T14:05:03Z`, a string of digits (nanoseconds since 1970), or a number (see below) |
| `endTimeUnixNano` or `end_time` | Yes | Same format |
| `attributes` | Yes, for Health | A flat object like the example, or the OpenTelemetry list form `[{"key": "…", "value": {"intValue": 1200}}]` |
| `name` | No | A label, like `chat claude-sonnet-4-5` |
| `kind` | No | For example `SPAN_KIND_CLIENT` |
| `status` | No | `{"code": 0}` for success, `{"code": 2, "message": "…"}` for an error |

### The attributes Health needs

| Attribute | Required | What it is |
| - | - | - |
| `gen_ai.operation.name` | **Yes, exactly `"chat"`** | Marks the span as a model call |
| `gen_ai.usage.input_tokens` | Yes, this or the next one | Prompt tokens |
| `gen_ai.usage.output_tokens` | Yes, this or the one above | Completion tokens |
| `gen_ai.response.model` or `gen_ai.request.model` | Recommended | The model name. Without it, the call shows as `unknown`. If you send both, Health uses the response model. |
| `gen_ai.usage.cost_usd` | Recommended | Cost in US dollars. `av.genai.cost_usd` and `ai.agent.llm.cost_usd` work too. |
| `gen_ai.system` | No | The provider |

> [!WARNING]
>
> 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](https://docs.agentvault.chat/security/overview.md) for what else the server can see.

## If something goes wrong

> [accordion] 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.

> [accordion] 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.

> [accordion] 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](#find-your-agents-hub-id).

> [accordion] 401 Invalid credentials
>
> The API key was revoked, expired or rotated, or the token is not valid. Get a new one.

> [accordion] 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.

> [accordion] 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.

> [accordion] 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](https://docs.agentvault.chat/guides/health.md)
* Build the rest of your agent: [Plugin SDK](https://docs.agentvault.chat/developers/plugin-sdk.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.