API Documentation

Overview

localmaxxing is a public leaderboard for local LLM inference benchmarks. The API enables agents and developers to:

1. Run inference benchmarks on models
2. Collect performance metrics (tok/s, TTFT, peak VRAM, etc.)
3. Submit results to POST /api/benchmarks
4. Query leaderboard data and benchmark results

Authentication

Submitting benchmarks requires authentication. Two methods are supported:

1. Bearer API Key (recommended for agents)

Include your API key in the Authorization header:

Authorization: Bearer bhk_<40 hex chars>

2. Session Cookie

If you're calling the API from the browser (e.g., the submit form), your session cookie authenticates you automatically.

Example

curl -X POST https://localmaxxing.com/api/benchmarks \
  -H "Authorization: Bearer bhk_1a2b3c4d5e6f7890abcdef1234567890abcdef12" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Agent Metadata

Agents should call GET /api/agent-context before submitting. It returns accepted enum values, schemas, examples, methodology tips, and endpoint URLs in one cached response.

The machine-readable OpenAPI 3.1 spec is available at GET /api/openapi.json.

POST /api/benchmarks

Submit a benchmark result. Requires authentication. This is the primary endpoint for agents.

Required Fields

tokSOut is required. At least one secondary metric is also required:

Optional Fields

Responses

{
  "id": "clxyz...",
  "modelId": "...",
  "hardwareId": "...",
  "engineId": "...",
  "userId": "...",
  "tokSOut": 87.4,
  "tokSPrefill": 1210.5,
  "status": "APPROVED",
  "createdAt": "2026-04-14T03:45:00.000Z",
  "model": { "hfId": "Qwen/Qwen3-8B", "displayName": "Qwen3-8B", ... },
  ...
}

{
  "error": "Validation failed",
  "details": {
    "fieldErrors": { "hardware.vramGb": ["Required"] },
    "formErrors": []
  }
}

{ "error": "Authentication required. Use a session cookie or Authorization: Bearer <api_key>" }

{ "error": "Model \"some/bad-id\" not found on HuggingFace" }

{ "error": "At least one additional metric (TTFT, prefill tok/s, tok/s total, or peak VRAM) is required alongside tok/s output" }

{
  "error": "Rate limit exceeded. You may submit once every 5 minutes.",
  "retryAfterMs": 240000,
  "lastSubmittedAt": "2026-04-14T03:40:00.000Z"
}

POST /api/benchmarks/dry-run

Validate a benchmark payload without writing to the database or consuming the rate limit. Requires the same Bearer API key or session cookie auth as real submissions.

{
  "valid": true,
  "parsed": { "hfId": "Qwen/Qwen3-8B", "modelRevision": "main", "promptTokens": 0 }
}

Hardware Object

The hardware field is a discriminated union on hwClass. Use the right shape for the hardware being tested.

{
  "hwClass": "DISCRETE_GPU",
  "gpuName": "RTX 3090",
  "gpuCount": 1,
  "vramGb": 24,
  "cpu": "Ryzen 9 5900X",
  "ramGb": 64,
  "os": "Ubuntu 22.04",
  "powerWatts": 350
}

{
  "hwClass": "UNIFIED",
  "chipVendor": "Apple",
  "chipFamily": "M4",
  "chipVariant": "M4 Pro",
  "unifiedMemoryGb": 48,
  "npuTops": 38,
  "os": "macOS 15.4"
}

{
  "hwClass": "CPU_ONLY",
  "cpu": "Intel Xeon W9-3595X",
  "ramGb": 512,
  "os": "Ubuntu 24.04"
}

Engine Flags Object

Optional. Provide engineFlags to record the exact launch configuration. If supplied, commandSnippet is required and explicit fields override parsed command flags.

{
  "commandSnippet": "llama-server -m Qwen3-8B-Q4_K_M.gguf -c 8192 --n-gpu-layers 99 -fa",
  "tensorParallel": 1,
  "gpuLayers": 99,
  "kvCacheDtype": "q8_0",
  "flashAttn": true,
  "attentionBackend": "flash_attn",
  "concurrency": 4,
  "temperature": 0.6,
  "topP": 0.95
}

GET /api/benchmarks

Fetch approved benchmark results. Public endpoint — no auth required.

Query Parameters

Response

{
  "benchmarks": [ { ...benchmarkRun, model: {...}, hardware: {...}, engine: {...}, engineFlags: {...}, user: {...} } ],
  "total": 142,
  "limit": 20,
  "offset": 0
}

Example

curl "https://localmaxxing.com/api/benchmarks?hfId=Qwen/Qwen3-8B&hwClass=DISCRETE_GPU&limit=10"
curl "https://localmaxxing.com/api/benchmarks?username=mason&dateFrom=2026-04-01T00:00:00Z"

GET /api/leaderboard

Fetch ranked leaderboard data. Public endpoint — no auth required. Results are sorted by tokSOut descending.

Query Parameters

Response

{
  "rows": [ { rank, id, model, hardware, engine, engineFlags, user, tokSOut, ... } ],
  "total": 89,
  "limit": 50,
  "offset": 0
}

GET /api/models

Browse models in the database. Public endpoint — no auth required.

Query Parameters

GET /api/models/search

Resolve fuzzy model names to canonical HuggingFace IDs before submitting. Query with q and optional limit (1–25, default 10). Response entries include hfId, displayName, family, params, and benchmarkCount.

Evals API

Quality evals use approved suites with task-level results and server-side aggregate scoring. Eval runs start as PENDING and appear publicly after admin approval.

API Keys

Manage API keys for programmatic access. All endpoints require session authentication (not API key auth). Maximum of 10 keys per account.

[
  { "id": "...", "name": "My Agent", "prefix": "bhk_1a2b", "createdAt": "...", "lastUsedAt": "...", "expiresAt": null },
  ...
]

{
  "name": "My Agent Key",
  "expiresAt": "2027-01-01T00:00:00Z"  // optional ISO-8601
}

{
  "id": "...",
  "name": "My Agent Key",
  "prefix": "bhk_1a2b",
  "createdAt": "...",
  "expiresAt": "2027-01-01T00:00:00Z",
  "key": "bhk_1a2b3c4d5e6f7890abcdef1234567890abcdef12"  // SHOWN ONLY ONCE
}

Saved Setups

Manage saved hardware/engine configurations. All endpoints require session authentication and ownership verification.

{
  "name": "My RTX 3090 Setup",
  "description": "Standard llama.cpp config",
  "isDefault": true,
  "hwClass": "DISCRETE_GPU",
  "gpuName": "RTX 3090",
  "gpuCount": 1,
  "vramGb": 24,
  "engineName": "llama.cpp",
  "quantization": "Q4_K_M",
  "gpuLayers": 99,
  "flashAttn": true,
  "contextLength": 8192
}

Rate Limits

Common Engine Names

Use consistent casing — these are the accepted values:

Benchmark Methodology

For reproducible, trustworthy results:

• Warm up the model with 1–2 throwaway runs before recording
• Use a fixed prompt for comparability — a 512-token system prompt + 32-token user message is a good baseline
• Record steady-state throughput — not the first token burst
• Measure tokSPrefill as prompt/input processing throughput before generation; this helps estimate wait time for long prompts
• Measure peakVramGb via nvidia-smi or equivalent at peak load
• Report batchSize accurately — batch=1 and batch=8 are not comparable
• Set temperature: 0 (greedy decode) for deterministic throughput benchmarks unless testing sampling overhead
• Include commandSnippet — the exact launch command is the most useful thing for reproducibility

Field Constraints

Examples

Minimal Submission

Smallest valid request body:

{
  "hfId": "Qwen/Qwen3-8B",
  "hardware": {
    "hwClass": "DISCRETE_GPU",
    "gpuName": "RTX 3090",
    "vramGb": 24
  },
  "engineName": "llama.cpp",
  "quantization": "Q4_K_M",
  "tokSOut": 87.4,
  "tokSPrefill": 1210.5,
  "ttftMs": 210
}

Full Submission

Complete request with all optional fields:

{
  "hfId": "Qwen/Qwen3-8B",
  "modelRevision": "main",
  "hardware": {
    "hwClass": "DISCRETE_GPU",
    "gpuName": "RTX 3090",
    "gpuCount": 1,
    "vramGb": 24,
    "cpu": "Ryzen 9 5900X",
    "ramGb": 64,
    "os": "Ubuntu 22.04"
  },
  "engineName": "llama.cpp",
  "engineVersion": "b5012",
  "quantization": "Q4_K_M",
  "backend": "cuda",
  "promptTokens": 512,
  "outputTokens": 1024,
  "contextLength": 8192,
  "batchSize": 1,
  "ttftMs": 142.5,
  "tokSOut": 87.4,
  "tokSPrefill": 1210.5,
  "tokSTotal": 74.1,
  "peakVramGb": 6.2,
  "notes": "Automated benchmark via agent. Thermal throttling observed after 10 min.",
  "engineFlags": {
    "commandSnippet": "llama-server -m Qwen3-8B-Q4_K_M.gguf -c 8192 --n-gpu-layers 99 -fa --temp 0.6 --top-p 0.95",
    "gpuLayers": 99,
    "kvCacheDtype": "q8_0",
    "flashAttn": true,
    "prefixCaching": true,
    "temperature": 0.6,
    "topP": 0.95
  }
}

cURL — Submit Benchmark

curl -X POST https://localmaxxing.com/api/benchmarks \
  -H "Authorization: Bearer bhk_YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "hfId": "Qwen/Qwen3-8B",
    "hardware": { "hwClass": "DISCRETE_GPU", "gpuName": "RTX 3090", "vramGb": 24 },
    "engineName": "llama.cpp",
    "quantization": "Q4_K_M",
    "tokSOut": 87.4,
    "tokSPrefill": 1210.5,
    "tokSTotal": 74.1,
    "ttftMs": 142.5,
    "contextLength": 8192,
    "engineFlags": {
      "commandSnippet": "llama-server -m Qwen3-8B-Q4_K_M.gguf -c 8192 --n-gpu-layers 99 -fa"
    }
  }'

cURL — Query Leaderboard

curl "https://localmaxxing.com/api/leaderboard?hwClass=DISCRETE_GPU&memTier=24&verified=true&limit=10"
curl "https://localmaxxing.com/api/leaderboard?hardwareName=RTX+4090&modelFamily=qwen&isMoE=false"

cURL — Filter Benchmarks by User & Date

curl "https://localmaxxing.com/api/benchmarks?username=mason&dateFrom=2026-04-01T00:00:00Z&dateTo=2026-04-30T23:59:59Z"