Hanzo Analytics

API reference · Hanzo Analytics API → — every endpoint, generated from the OpenAPI spec.

Hanzo Analytics provides dashboards and APIs for usage, latency, cost, and reliability metrics across the Hanzo platform. It aggregates data from all services to give operators and developers real-time visibility.

Features

Usage Metrics: Requests, tokens, bandwidth, and throughput per service
Cost Tracking: Per-project budgets, spend breakdowns, and forecasting
Operational Health: Error rates, latency percentiles, and saturation signals
Alerting: Threshold-based alerts via webhooks, Slack, or PagerDuty
Export: CSV/JSON exports and streaming to BI pipelines

Dashboard

The Analytics dashboard is available at console.hanzo.ai:

┌─────────────────────────────────────────────────────────────┐
│  Hanzo Analytics                         Last 24h ▾  ⟳     │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  Requests    Tokens          Cost         Latency (p99)     │
│  ━━━━━━━━    ━━━━━━━━━━      ━━━━━━━━     ━━━━━━━━━━━━━     │
│  1.2M/day    847M tokens     $2,341/day   312ms             │
│  ↑ 15%       ↑ 22%           ↑ 18%        ↓ 8%              │
│                                                              │
│  ┌─────────────────────────────────────────────────────┐    │
│  │  Request Volume                                      │    │
│  │  ▁▂▃▄▅▆▇█▇▆▅▄▃▂▁▁▂▃▄▅▆▇▇▆▅▄                      │    │
│  │  00:00    06:00    12:00    18:00    24:00           │    │
│  └─────────────────────────────────────────────────────┘    │
│                                                              │
│  Top Models           │  Cost by Project                    │
│  ─────────────────    │  ─────────────────                  │
│  claude-sonnet  42%   │  platform    $1,205                 │
│  gpt-4o         28%   │  bot         $672                   │
│  llama-3.1      15%   │  commerce    $284                   │
│  gemini-pro      8%   │  internal    $180                   │
│  other           7%   │                                     │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Metrics API

Every call is on the one Hanzo API host, https://api.hanzo.ai, with your normal bearer.

/v1/analytics is READ ONLY — it is the lens over the event plane, never a way into it. Writing is one door, POST /v1/event, and one door is the whole rule: send a single event, a bare array, or {"batch":[…]} and they all land the same way. (There is no /v1/event/batch, and the older /v1/analytics, /v1/analytics/batch and /v1/tracker write paths are retired — /v1/tracker is the tracker product, not an ingest path.)

Method	Path	Purpose
`GET`	`/v1/analytics/overview?range=`	One roll-up per lens for the range
`GET`	`/v1/analytics/timeseries?range=`	Bucketed series (requests, tokens, spend)
`GET`	`/v1/analytics/top?range=`	Leaderboards — top models, providers, pages
`GET`	`/v1/analytics/health`	Datastore + per-lens availability
`POST`	`/v1/event`	Capture — one event, an array, or `{"batch":[…]}`

range accepts 24h, 7d, 30d, … The org is never passed by hand: the gateway re-mints X-Org-Id from your validated token, and every response echoes the resolved scope.

Overview

curl -fsS "https://api.hanzo.ai/v1/analytics/overview?range=7d" \
  -H "Authorization: Bearer $HANZO_API_KEY"

{
  "range": "7d",
  "start": "2026-07-18T22:21:04Z",
  "end": "2026-07-25T22:21:04Z",
  "interval": "day",
  "scope": { "org": "hanzo" },
  "llm": {
    "available": true,
    "requests": 8661,
    "tokens": 130586947,
    "promptTokens": 126558231,
    "completionTokens": 4028716,
    "spendCents": 206418,
    "models": 115,
    "providers": 7,
    "errors": 212,
    "errorRate": 0.024,
    "source": "hanzo.cloud_usage"
  },
  "web": {
    "available": true,
    "pageviews": 4164,
    "visitors": 1159,
    "sessions": 875,
    "source": "hanzo.events"
  }
}

Each lens carries available and the source table it read, so a zero is never ambiguous — you can tell "nothing happened" from "that lens is not wired up".

Time series

curl -fsS "https://api.hanzo.ai/v1/analytics/timeseries?range=7d" \
  -H "Authorization: Bearer $HANZO_API_KEY"

{
  "range": "7d",
  "interval": "day",
  "scope": { "org": "hanzo" },
  "series": [
    { "t": "2026-07-18T00:00:00Z", "requests": 399, "tokens": 57306163, "spendCents": 88746 },
    { "t": "2026-07-19T00:00:00Z", "requests": 5165, "tokens": 11717502, "spendCents": 23348 }
  ]
}

Leaderboards

curl -fsS "https://api.hanzo.ai/v1/analytics/top?range=7d" \
  -H "Authorization: Bearer $HANZO_API_KEY"

{
  "range": "7d",
  "scope": { "org": "hanzo" },
  "models": {
    "available": true,
    "items": [
      { "model": "zen5", "provider": "hanzo", "requests": 483, "tokens": 64757117, "spendCents": 98732, "pct": 48.2 }
    ]
  }
}

Health

curl -fsS https://api.hanzo.ai/v1/analytics/health

{
  "datastore": true,
  "lenses": {
    "events": { "available": true, "table": "hanzo.events" },
    "llm": { "available": true, "table": "hanzo.cloud_usage" }
  },
  "service": "analytics",
  "status": "ok",
  "warehouse": "hanzo"
}

Cost and budgets

Spend is metered into the same balance every product draws from, so cost lives with billing rather than in a second budgeting system:

Balance and itemized usage — GET /v1/billing/balance, GET /v1/billing/usage
Spend alerts — GET · POST /v1/billing/spend-alerts
Roll-ups by model, provider, and day — the analytics endpoints above

See Credits & Billing.

Cost breakdown dimensions

Dimension	Where
By model	`/v1/analytics/top` → `models.items[].spendCents`
By provider	`/v1/analytics/top` → `models.items[].provider`
By time	`/v1/analytics/timeseries` → `series[].spendCents`
By transaction	`/v1/billing/usage` → `usage[].metadata`

Operational Health

Request rate, error rate, and latency for a running service come from the observability lens, not this one — see Hanzo o11y:

curl -fsS "https://api.hanzo.ai/v1/o11y/metrics?product=cloud" \
  -H "Authorization: Bearer $HANZO_API_KEY"

Metric	Description	Alert Threshold
`error_rate`	Percentage of 4xx/5xx responses	> 1%
`latency_p50`	Median response time	> 200ms
`latency_p99`	99th percentile response time	> 2000ms
`availability`	Successful requests / total requests	< 99.9%

SDK Integration

The analytics endpoints are plain REST on api.hanzo.ai, so any HTTP client works — no analytics-specific SDK to install.

Python

import httpx, os

r = httpx.get(
    "https://api.hanzo.ai/v1/analytics/top",
    params={"range": "7d"},
    headers={"Authorization": f"Bearer {os.environ['HANZO_API_KEY']}"},
)
for row in r.json()["models"]["items"]:
    print(f"{row['model']}: {row['requests']} requests, ${row['spendCents'] / 100:.2f}")

TypeScript

const res = await fetch('https://api.hanzo.ai/v1/analytics/top?range=7d', {
  headers: { Authorization: `Bearer ${process.env.HANZO_API_KEY}` },
})
const { models } = await res.json()

for (const row of models.items) {
  console.log(`${row.model}: ${row.requests} requests, $${(row.spendCents / 100).toFixed(2)}`)
}

Platform management and billing

AI API — primary source of usage data

Runtime telemetry and performance metrics

Billing and payment integration

Hanzo Analytics

On this page