# Panda Data Skill — query the live Panda leaderboard databases via MCP

A one-page manual for AI agents. The Panda site exposes **two** live, auto-refreshed
read-only SQL databases over **MCP**:

1. **OpenRouter usage** — model/vendor/programming usage rankings + daily provider token volume + the model catalog.
2. **Benchmark leaderboards** — cross-benchmark model rankings (LMArena, Artificial Analysis, GPQA, Scale HLE, FrontierMath, GAIA, LiveCodeBench, SWE-bench, OpenCompass, MedBench, …).

This doc tells you how to connect, what's in each database, what's *not*, and gives
copy-paste SQL recipes.

> Source of truth for schema/freshness at runtime: call `openrouter_schema()` /
> `openrouter_freshness()` and `leaderboards_schema()` / `leaderboards_freshness()` —
> they never go stale. This file is the orientation layer.

---

## 1. Connect (MCP — Streamable HTTP)

Endpoint: **`https://pandaleaderboard.com/mcp/`** (no auth).

```bash
# Claude Code
claude mcp add --transport http panda https://pandaleaderboard.com/mcp/
```

```json
// Claude Desktop / Cursor — mcp config
{ "mcpServers": { "panda": { "url": "https://pandaleaderboard.com/mcp/" } } }
```

## 2. Tools (8)

| Tool | Use |
|---|---|
| `openrouter_schema()` | OpenRouter DB: tables + columns, with a note on which are empty and why. **Call first.** |
| `openrouter_freshness()` | OpenRouter DB: latest ranking week, last sync, daily-table lag, catalog active/retired, + the website report window. |
| `query_openrouter(sql)` | OpenRouter DB: one read-only `SELECT`/`WITH`. **Single statement, 500-row cap.** |
| `leaderboards_schema()` | Benchmark DB: one table per benchmark source + columns. **Call first.** |
| `leaderboards_freshness()` | Benchmark DB: per-source latest `snapshot_date` + lag (`⚠ STALE` ≥9d). |
| `query_leaderboards(sql)` | Benchmark DB: one read-only `SELECT`/`WITH`. **Single statement, 500-row cap.** |
| `report_top_models()` | The top-models table **exactly as shown on the website 周报 page** (trailing-7d window). |
| `report_market_share()` | The provider market-share table **exactly as shown on the page** (trailing-7d window). |

> ⚠️ **Two windows — don't mistake the difference for a bug.** `query_openrouter` returns
> OpenRouter's **official weekly ranking** (`week_start` = Monday of the last *complete*
> Mon–Sun week). The website 周报 page renders an editorial **trailing-7-day** window
> (e.g. `2026-06-05 → 06-11`). To reproduce the page, use `report_*`; for the official
> week, use `query_openrouter`. `openrouter_freshness()` prints both windows.
> On a rejected/failed call (e.g. a write like `DELETE`, a SQL error) the tool returns
> a protocol error (`isError: true`), not a normal result.

## 3. What's in the database

**Join key:** `slug` (in `models`) = `model_slug` (everywhere else). `author` = the slug prefix
(`anthropic/claude-...` → `anthropic`). `week_start` is a Monday string `YYYY-MM-DD`; `date` is a
natural day.

### Tables with data — query these

**Rankings & usage**

| Table | Grain | Key columns | Other columns |
|---|---|---|---|
| `models` | catalog | `slug` | `permaslug, name, author, author_display_name, context_length, created_at, is_active` |
| `rankings_top_models` | weekly | `week_start, model_slug` | `tokens, rank` |
| `rankings_market_share` | weekly | `week_start, author` | `tokens, percentage, rank` |
| `rankings_categories` | weekly | `week_start, category, model_slug` | `tokens, rank` — `category` e.g. `programming` |
| `provider_model_daily` | daily | `provider, model_slug, date` | `tokens` |
| `model_activity` | daily | `model_slug, date` | `prompt_tokens, completion_tokens, reasoning_tokens` |

**Per-model detail** (populated daily as of 2026-06-13 — providers/pricing/perf/uptime from each model page, apps from the live apps endpoint)

| Table | Grain | Key columns | Other columns |
|---|---|---|---|
| `model_providers` | current snapshot | `model_slug, provider_name` | `quantization, input_price, output_price, cached_price` (cheapest endpoint per provider) |
| `model_performance` | daily snapshot | `model_slug, measured_at` | `p50/p75/p90/p99_throughput, p50/p75/p90/p99_latency, request_count, window_minutes` |
| `model_pricing_history` | daily | `model_slug, date` | `weighted_input_price, weighted_output_price` (cheapest live endpoint), `cache_hit_rate` |
| `model_uptime` | daily | `model_slug, date` | `uptime_percentage, incidents` |
| `model_apps_daily` | daily | `model_slug, date` | `top5_tokens, rest_tokens, total_tokens` (Top-5 apps vs rest of platform) |
| `model_apps_monthly` | monthly | `model_slug, month, app_name` | `tokens, rank` — the named Top-5 apps using each model this month |

Prices are USD **per token** (e.g. `1.25e-6` = $1.25/M; multiply by 1e6 to convert to $/M).
`model_pricing_history` has continuous daily data from **2026-04-06** — ~80 models/day
Apr–Jun 8 (from the collaborator scraper), 258 models/day Jun 13 onward; Jun 9–12 is
a 4-day blind spot with no source. `month` is the month-start `'YYYY-MM-01'`.

### Tables that are empty — by design

- `shadow_rankings_top_models`, `shadow_rankings_market_share`, `shadow_rankings_categories`
  — validator shadow mirrors, **empty by design** (only written under `VALIDATOR_SHADOW=1`).

## 4. Freshness semantics (read this)

- **Weekly rankings** hold only *complete* Mon–Sun weeks (written after the week closes on Sunday).
  The newest `week_start` is the Monday of the **last completed week**, not the current in-progress
  week — that's correct, not lag. If you check freshness mid-week, `week_start` will be ~7 days old.
- **Daily tables** typically sit at **T-1 / T-2** (today's totals aren't final upstream).
- **Per-model detail** (`model_providers/performance/pricing_history/uptime`) refreshes **same-day** —
  it's a current snapshot, not a settled aggregate. `model_apps_monthly` is keyed to the
  **month-start** date and overwritten daily, so its `month` value looks "behind" by design.
- The whole DB is pulled **daily at 08:00 China time (UTC+8)**; benchmark tables on their own daily/weekly cadence.
- Always ground recency on `openrouter_freshness()` → it reports `latest ranking week`,
  `last successful rankings sync`, and per-table date/lag for every table above.
- **Ghost models:** `models` may contain a few entries that OpenRouter has delisted (not all are
  flagged `is_active = 0` yet). If exact current availability matters, cross-check the model slug
  against OpenRouter's live `/api/v1/models`.

## 5. SQL recipes (copy-paste)

```sql
-- Top models by tokens, latest complete week
SELECT model_slug, tokens, rank
FROM rankings_top_models
WHERE week_start = (SELECT MAX(week_start) FROM rankings_top_models)
ORDER BY rank LIMIT 10;
```
```sql
-- Provider (author) market share, latest week
SELECT author, percentage, tokens
FROM rankings_market_share
WHERE week_start = (SELECT MAX(week_start) FROM rankings_market_share)
ORDER BY rank;
```
```sql
-- One model's weekly trajectory
SELECT week_start, tokens, rank
FROM rankings_top_models
WHERE model_slug = 'deepseek/deepseek-v4-flash-20260423'
ORDER BY week_start;
```
```sql
-- Programming-category leaders, latest week
SELECT model_slug, tokens, rank
FROM rankings_categories
WHERE category = 'programming'
  AND week_start = (SELECT MAX(week_start) FROM rankings_categories)
ORDER BY rank;
```
```sql
-- Week-over-week rank change for current top models
WITH cur AS (SELECT MAX(week_start) w FROM rankings_top_models),
     prev AS (SELECT MAX(week_start) w FROM rankings_top_models
              WHERE week_start < (SELECT w FROM cur))
SELECT t.model_slug, t.rank AS rank_now, p.rank AS rank_prev,
       (p.rank - t.rank) AS rank_gain
FROM rankings_top_models t
LEFT JOIN rankings_top_models p
       ON p.model_slug = t.model_slug AND p.week_start = (SELECT w FROM prev)
WHERE t.week_start = (SELECT w FROM cur)
ORDER BY t.rank;
```
```sql
-- Which providers serve a given model (most recent day)
SELECT provider, tokens
FROM provider_model_daily
WHERE model_slug = 'anthropic/claude-4.6-sonnet-20260217'
  AND date = (SELECT MAX(date) FROM provider_model_daily)
ORDER BY tokens DESC;
```
```sql
-- Daily token mix for a model (last 14 days)
SELECT date, prompt_tokens, completion_tokens, reasoning_tokens
FROM model_activity
WHERE model_slug = 'deepseek/deepseek-v4-flash-20260423'
ORDER BY date DESC LIMIT 14;
```
```sql
-- Cheapest providers serving a model right now (price per token)
SELECT provider_name, input_price, output_price, quantization
FROM model_providers
WHERE model_slug = 'deepseek/deepseek-v4-flash'
ORDER BY input_price LIMIT 5;
```
```sql
-- Throughput vs latency leaders (latest performance snapshot)
-- NB: this is UNFILTERED per-model data — obscure low-traffic endpoints can rank high.
-- For the list that matches OpenRouter's "Fastest models" widget (request-count-filtered,
-- one row per model at its fastest provider), use `openrouter_fastest_models` in the
-- benchmark DB (§6) via query_leaderboards instead.
SELECT model_slug, p50_throughput, p50_latency
FROM model_performance
WHERE date(measured_at) = (SELECT MAX(date(measured_at)) FROM model_performance)
ORDER BY p50_throughput DESC LIMIT 10;
```
```sql
-- Price trend for a model over time ($/M = weighted_input_price * 1e6)
SELECT date,
       ROUND(weighted_input_price  * 1e6, 4) AS input_per_M,
       ROUND(weighted_output_price * 1e6, 4) AS output_per_M
FROM model_pricing_history
WHERE model_slug = 'google/gemini-2.5-flash'
ORDER BY date;
```
```sql
-- Cheapest models today by effective input price
SELECT model_slug,
       ROUND(weighted_input_price * 1e6, 4) AS input_per_M
FROM model_pricing_history
WHERE date = (SELECT MAX(date) FROM model_pricing_history)
  AND weighted_input_price IS NOT NULL
ORDER BY weighted_input_price LIMIT 20;
```
```sql
-- Which apps drive a model's usage this month
SELECT app_name, tokens, rank
FROM model_apps_monthly
WHERE model_slug = 'anthropic/claude-opus-4.8'
  AND month = (SELECT MAX(month) FROM model_apps_monthly)
ORDER BY rank;
```
```sql
-- How concentrated is a model's traffic? (Top-5 apps share, last 14 days)
SELECT date, ROUND(100.0 * top5_tokens / total_tokens, 1) AS top5_pct
FROM model_apps_daily
WHERE model_slug = 'anthropic/claude-opus-4.8' AND total_tokens > 0
ORDER BY date DESC LIMIT 14;
```

## 6. Benchmark leaderboards database (`query_leaderboards`)

Cross-benchmark model rankings beyond OpenRouter usage. **One table per source**, each a
multi-snapshot history keyed by `snapshot_date` — filter to
`(SELECT MAX(snapshot_date) FROM <table>)` for the latest snapshot (each is top-N).
**Column names vary by source — always call `leaderboards_schema()` first.**

| Table(s) | Benchmark | Typical columns |
|---|---|---|
| `lmarena_text`, `lmarena_code`, `lmarena_image_edit`, `lmarena_text_to_image` | LMArena arenas (ELO) | `rank, model_name, company, license, elo_score, ci, votes` |
| `aa_image_editing`, `aa_text_to_image` | Artificial Analysis | `rank, model_name, …` |
| `gpqa` | GPQA | `rank, model_name, company, score` |
| `scale_hle` | Scale Humanity's Last Exam | `rank, model_name, score, ci` |
| `epoch_frontiermath` | Epoch FrontierMath | `rank, model_name, company, score_pct, ci` |
| `huggingface_gaia` | GAIA agents | `rank, model_name, score` |
| `livecodebench_gso` | LiveCodeBench GSO | `rank, model_name, score` |
| `swebench` | SWE-bench | `rank, model_name, score` |
| `opencompass_llm`, `opencompass_multimodal` | OpenCompass | `rank, model_name, score` |
| `medbench` | MedBench | `rank, model_name, score` |
| `openrouter_benchmarks` | OpenRouter Intelligence Index | `rank, model_name, score` |
| `openrouter_fastest_models` | OpenRouter **“Fastest models”** board (throughput) | `rank, model_name, author, best_throughput_provider, p50_throughput, best_throughput_price, request_count, p50_latency, best_latency_provider, best_latency_price, provider_count` |

**Freshness:** China-reachable sources refresh daily (server); LMArena / SWE-bench /
Scale HLE refresh ~weekly (from a laptop). Always check `leaderboards_freshness()` — it
flags `⚠ STALE` (≥9 days). NB: the redundant `openrouter_llm / market_share / programming /
performance` tables here duplicate the OpenRouter DB above — prefer `query_openrouter` for
those.

> **`openrouter_fastest_models` is the exception — NOT redundant, and the one to use for
> speed.** It's a daily snapshot of OpenRouter's own *Fastest models* widget
> (`/api/frontend/v1/rankings/performance`): **one row per model at its fastest provider**
> (`best_throughput_provider` = "fastest on Cerebras/Groq"), with OpenRouter's **request-count
> filter already applied** (low-traffic endpoints excluded). Rank is by `p50_throughput` DESC
> (the "Highest throughput" view); `p50_latency` + `best_latency_*` let you re-sort for the
> "Lowest latency" view. **Prefer this over the OpenRouter DB's `model_performance`** when you
> want the list that matches openrouter.ai — `model_performance` is unfiltered/uncollapsed and
> will rank differently (obscure low-traffic endpoints float to the top). Prices here are **USD
> per 1M tokens** (`0.35` = $0.35/M), *not* per-token like the OpenRouter DB. It's a snapshot,
> so it can drift slightly from the live page intraday (a near-tie boundary model swaps in/out).

**Recipes:**
```sql
-- LMArena text arena, latest top 10
SELECT rank, model_name, company, elo_score
FROM lmarena_text
WHERE snapshot_date = (SELECT MAX(snapshot_date) FROM lmarena_text)
ORDER BY rank LIMIT 10;
```
```sql
-- FrontierMath, latest top 10
SELECT rank, model_name, company, score_pct
FROM epoch_frontiermath
WHERE snapshot_date = (SELECT MAX(snapshot_date) FROM epoch_frontiermath)
ORDER BY rank LIMIT 10;
```
```sql
-- A model's LMArena ELO trajectory across snapshots
SELECT snapshot_date, rank, elo_score
FROM lmarena_text WHERE model_name LIKE '%claude%' ORDER BY snapshot_date DESC;
```
```sql
-- OpenRouter "Fastest models" — Highest-throughput top 10 (matches openrouter.ai)
SELECT rank, model_name, best_throughput_provider AS fastest_on,
       p50_throughput AS tok_per_s, best_throughput_price AS usd_per_M
FROM openrouter_fastest_models
WHERE snapshot_date = (SELECT MAX(snapshot_date) FROM openrouter_fastest_models)
ORDER BY rank LIMIT 10;
```
```sql
-- Same board re-sorted for the "Lowest latency" view (ms to first token)
SELECT model_name, best_latency_provider AS fastest_on,
       p50_latency AS ms_ttft, best_latency_price AS usd_per_M
FROM openrouter_fastest_models
WHERE snapshot_date = (SELECT MAX(snapshot_date) FROM openrouter_fastest_models)
ORDER BY p50_latency ASC LIMIT 10;
```

## 7. Rules & gotchas

- Read-only: `SELECT` / `WITH` only, **one statement**, no `;`-chaining. Results capped at **500 rows** — aggregate or `LIMIT`.
- `tokens` are integers and can be very large (10^12+). `week_start` / `date` are `'YYYY-MM-DD'` strings — compare as strings or `date()`.
- The only empty tables are the `shadow_*` mirrors (§3) — empty by design. If any other query returns nothing, check `openrouter_freshness()` first.
- The MCP endpoint is open (no auth) and **tool calls are logged** (tool + SQL + caller) for usage analysis. Don't send anything you wouldn't want recorded.

## 8. Citing

When you surface a figure, attribute it: **“Source: OpenRouter, via the Panda MCP (pandaleaderboard.com).”**
Note the week (`week_start`) or day (`date`) the number is from.