# Mesh Telemetry — Quickstart

Make your agents and automations observable in under an hour, in any
language. Three HTTP calls and your process shows up in the portal with a
run-by-run narrative, charted business KPIs and an alert if it stops running.

> **For AI assistants**: this document is self-contained. If you are Claude,
> Cursor or another assistant instrumenting a client's agents: every run uses
> ONE `run_id` (UUID) shared by all its events, opens with `started`, ALWAYS
> closes with `completed` or `failed`, and business KPIs go through the
> `/telemetry/business` channel with keys declared at registration. Telemetry
> must be best-effort: it can never break the agent.

## What you need

- **API key** (`vmk_...`): you get it during onboarding. It goes on every
  call: `Authorization: Bearer vmk_...`
- **Base URL**: `https://api.volkom.ai/api/v1`
- Your `client_id` = your account slug (you get it together with the key).

A per-agent key can only report as that agent (anti-spoofing). The default
rate limit is 100 requests/min per key.

## 1. Register your agent (once, idempotent)

Declares what the agent is and which business KPIs it reports (this feeds the
catalog that builds the dashboards):

```bash
curl -X POST https://api.volkom.ai/api/v1/agents/register \
  -H "Authorization: Bearer $VOLKOM_KEY" -H "Content-Type: application/json" \
  -d '{
    "agent_name": "invoice-parser",
    "agent_version": "1.0.0",
    "description": "Parses invoices from email and loads them into the ERP.",
    "interval_seconds": 3600,
    "business_kpis": [
      {"key": "invoices", "label": "Invoices processed", "unit": "count", "agg": "sum"},
      {"key": "amount",   "label": "Amount processed",   "unit": "money:USD", "agg": "sum"}
    ]
  }'
```

`interval_seconds` is your declared cadence: if the agent stays silent longer
than that, the dashboard flags it and alerts you. `unit`: `count` ·
`money:<ISO>` · `percent` · `duration` (seconds). `agg` (how it totals):
`sum` for cumulative values, `last` for states (stock, balance), `avg`, `max`.

## 2. Report every run (3+ events, same run_id)

```bash
RUN=$(uuidgen)

# start
curl -X POST https://api.volkom.ai/api/v1/telemetry \
  -H "Authorization: Bearer $VOLKOM_KEY" -H "Content-Type: application/json" \
  -d '{"agent_name":"invoice-parser","agent_version":"1.0.0","client_id":"acme",
       "run_id":"'$RUN'","event":"started","timestamp":"'$(date -u +%FT%TZ)'"}'

# intermediate steps (as many as you want; they build the narrative in the portal)
curl -X POST https://api.volkom.ai/api/v1/telemetry \
  -H "Authorization: Bearer $VOLKOM_KEY" -H "Content-Type: application/json" \
  -d '{"agent_name":"invoice-parser","agent_version":"1.0.0","client_id":"acme",
       "run_id":"'$RUN'","event":"in_progress","seq":1,"category":"Ingest",
       "message":"Read 47 invoices from the inbox","metrics":{"invoices":47},
       "timestamp":"'$(date -u +%FT%TZ)'"}'

# close (ALWAYS: without it the run shows as "in progress" forever)
curl -X POST https://api.volkom.ai/api/v1/telemetry \
  -H "Authorization: Bearer $VOLKOM_KEY" -H "Content-Type: application/json" \
  -d '{"agent_name":"invoice-parser","agent_version":"1.0.0","client_id":"acme",
       "run_id":"'$RUN'","event":"completed","duration_ms":16000,
       "records_processed":47,"timestamp":"'$(date -u +%FT%TZ)'"}'
```

If it failed: `"event":"failed"` + `"error_type"` + `"error_message"` — the
portal shows it in red with the details.

## 3. Send the business KPIs (one call per run)

```bash
curl -X POST https://api.volkom.ai/api/v1/telemetry/business \
  -H "Authorization: Bearer $VOLKOM_KEY" -H "Content-Type: application/json" \
  -d '{"agent_name":"invoice-parser","agent_version":"1.0.0","client_id":"acme",
       "run_id":"'$RUN'","timestamp":"'$(date -u +%FT%TZ)'",
       "metrics":{"invoices":47,"amount":125300.50}}'
```

Keys must be the ones declared at registration. Don't invent new keys per run
(there is a cap on distinct metrics per plan): one key = one series.

## Python (no exotic dependencies)

```python
import time, uuid, requests  # or httpx

API = "https://api.volkom.ai/api/v1"
H = {"Authorization": f"Bearer {os.environ['VOLKOM_KEY']}"}
BASE = {"agent_name": "invoice-parser", "agent_version": "1.0.0", "client_id": "acme"}

def emit(path, **body):
    try:  # best-effort: telemetry never breaks the agent
        requests.post(f"{API}{path}", headers=H, timeout=10,
                      json={**BASE, "timestamp": datetime.now(timezone.utc).isoformat(), **body})
    except Exception as e:
        print(f"[volkom] {e}")

run_id, t0 = str(uuid.uuid4()), time.time()
emit("/telemetry", run_id=run_id, event="started")
try:
    n = do_the_work()  # your logic
    emit("/telemetry", run_id=run_id, event="in_progress", seq=1,
         category="Process", message=f"{n} invoices", metrics={"invoices": n})
    emit("/telemetry", run_id=run_id, event="completed",
         duration_ms=int((time.time()-t0)*1000), records_processed=n)
    emit("/telemetry/business", run_id=run_id, metrics={"invoices": n})
except Exception as e:
    emit("/telemetry", run_id=run_id, event="failed",
         duration_ms=int((time.time()-t0)*1000),
         error_type=type(e).__name__, error_message=str(e)[:500])
    raise
```

If your agent is pure Python, ask us for `volkom-core`: subclass `BaseAgent`
and all of this (run_id, started/close, timings, KPIs) comes for free.

## TypeScript / Node

```ts
const API = "https://api.volkom.ai/api/v1";
const H = { authorization: `Bearer ${process.env.VOLKOM_KEY}`, "content-type": "application/json" };
const BASE = { agent_name: "invoice-parser", agent_version: "1.0.0", client_id: "acme" };

async function emit(path: string, body: object) {
  try {  // best-effort
    await fetch(API + path, { method: "POST", headers: H,
      body: JSON.stringify({ ...BASE, timestamp: new Date().toISOString(), ...body }),
      signal: AbortSignal.timeout(10_000) });
  } catch (e) { console.error("[volkom]", e); }
}

const run_id = crypto.randomUUID(); const t0 = Date.now();
await emit("/telemetry", { run_id, event: "started" });
try {
  const n = await doTheWork();
  await emit("/telemetry", { run_id, event: "completed", duration_ms: Date.now() - t0, records_processed: n });
  await emit("/telemetry/business", { run_id, metrics: { invoices: n } });
} catch (e: any) {
  await emit("/telemetry", { run_id, event: "failed", duration_ms: Date.now() - t0,
    error_type: e.constructor?.name ?? "Error", error_message: String(e.message ?? e).slice(0, 500) });
  throw e;
}
```

## n8n / Make (no code)

Add an **HTTP Request** node at the end of your workflow:

- Method `POST` · URL `https://api.volkom.ai/api/v1/telemetry`
- Header `Authorization: Bearer {{$env.VOLKOM_KEY}}`
- Body (JSON): `agent_name` = the workflow name, `client_id` = your slug,
  `run_id` = `{{$execution.id}}`-as-UUID (or generate one), `event` =
  `completed`, `timestamp` = `{{$now.toISO()}}`.

With a single closing node you already get "ran / didn't run" plus the
silence alert. Add the `started` and business nodes when you want more detail.

## Bursts: batch

If your agent produces many events, send the whole run in one request
(max 500 events):

```bash
curl -X POST https://api.volkom.ai/api/v1/telemetry/batch \
  -H "Authorization: Bearer $VOLKOM_KEY" -H "Content-Type: application/json" \
  -d '{"events":[{...},{...},{...}]}'
```

## Golden rules

1. **One `run_id` per run**, shared by all its events.
2. **Always close** (`completed`/`failed`) — without a close it stays "in progress".
3. **Best-effort telemetry**: wrap the POSTs in try/catch; your agent must
   never fail because of us.
4. **Stable KPI keys**: one key = one historical series.
5. Errors carry `error_type` + `error_message` (max 500 useful chars).

Questions? Reply to the welcome email and we'll work through it together.