# Live Dashboard

> Public HTML dashboard at /dashboard showing real-time KPIs, throttle heatmap, model health, and project usage for the gateway.

Canonical: https://ai-gateway.sassmaker.com/docs/dashboard

## Endpoint

```
GET /dashboard          # canonical
GET /live               # alias
GET /v1/dashboard       # alias
```

**Authentication:** None — public.

A single self-contained HTML page that visualizes the gateway's live health and usage. No build step, no framework — just `<script>` tags pulling data every 5 seconds from the gateway's own JSON endpoints.

## What You See

- **KPIs** — total requests, final gateway success, gateway failures, and whether fallback is covering upstream flakiness.
- **Timeline chart** — weekly successful vs failed request volume from [`/v1/analytics`](https://ai-gateway.sassmaker.com/analytics).
- **Provider breakdown** — success rate, throttle rate, and latency per provider, derived from [`/v1/stats/providers`](https://ai-gateway.sassmaker.com/provider-stats).
- **Throttle heatmap** — which providers are hitting rate limits and how often.
- **Live model health** — rolling upstream samples, upstream success rate, avg/P90/P99 latency, usage, and cooldown expiry from [`/health`](https://ai-gateway.sassmaker.com/health). These are provider attempts before fallback, not final user-visible request outcomes.
- **Top models** — the models actually serving traffic, ranked by request volume.
- **Projects** — aggregate per-`project_id` usage from [`/v1/analytics`](https://ai-gateway.sassmaker.com/analytics).

## Auto-Refresh

The page polls every 5 seconds with `cache-control: no-store`. Open it in a second monitor and you get a live ops view of the gateway with zero setup.

## How It's Built

Everything is inlined in `src/dashboard-html.ts` and served as a single HTML string. Chart.js is loaded from a CDN (`cdn.jsdelivr.net`). The page consumes these public JSON endpoints:

| Endpoint | Purpose |
|---|---|
| [`/v1/analytics`](https://ai-gateway.sassmaker.com/analytics) | Total requests, per-project, per-model, daily series. |
| [`/health`](https://ai-gateway.sassmaker.com/health) | Live per-model health snapshot. |
| [`/v1/stats/providers`](https://ai-gateway.sassmaker.com/provider-stats) | Per-provider throttle / success / cooldown rollup. |

All three are public, so the dashboard is too.

## Usage

Just open the URL in a browser:

```
https://ai-gateway.sassmaker.com/dashboard
```

The `/live` and `/v1/dashboard` paths serve the exact same HTML — useful if you want a memorable short URL to bookmark or a REST-namespaced path to expose to partners.

## Embedding

You can embed the dashboard in an internal tool with an iframe. Since no auth is required, there's no token handling:

```html
<iframe
  src="https://ai-gateway.sassmaker.com/dashboard"
  width="100%"
  height="900"
  style="border: 0; border-radius: 8px"
></iframe>
```

:::caution[Public by design]
The dashboard exposes aggregate usage, provider health, and project ids. Do not rely on URL obscurity for privacy — anything visible in the dashboard is fetched from already-public endpoints. If you need to hide project ids, namespace them with a random prefix (e.g. `acme_prod_ab92f1`) rather than leaving them guessable.
:::

## Related

- [`/v1/analytics`](https://ai-gateway.sassmaker.com/analytics) — raw numbers feeding the dashboard.
- [`/health`](https://ai-gateway.sassmaker.com/health) — per-model health JSON.
- [`/v1/stats/providers`](https://ai-gateway.sassmaker.com/provider-stats) — per-provider rollup JSON.