Pagination

The SupraBench dataset is small by API standards (low thousands of models, low hundreds of benchmarks). For now, all list endpoints use simple limit-based access; full cursor pagination ships when any single resource crosses 10 000 rows.

Today: limit-based

Each list endpoint accepts a limit query parameter (1–500, default 100). Results are returned sorted by the natural order of the resource — Supra-Score descending for models, quality score descending for benches, alphabetical for tags.

curl "https://api.suprabench.com/v1/models?limit=20" \
  -H "Authorization: Bearer $SUPRABENCH_KEY"

models = requests.get(
    "https://api.suprabench.com/v1/models",
    params={"limit": 20},
    headers={"Authorization": f"Bearer {KEY}"},
).json()

const r = await fetch("https://api.suprabench.com/v1/models?limit=20", {
  headers: { Authorization: `Bearer ${KEY}` },
});
const models = await r.json();

req, _ := http.NewRequest("GET",
    "https://api.suprabench.com/v1/models?limit=20", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SUPRABENCH_KEY"))
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var models []map[string]any
json.NewDecoder(resp.Body).Decode(&models)

Default and max

Out-of-range values are clamped, not rejected — limit=99999 silently becomes the per-endpoint max.

Client-side filtering

For browsing all 5 000 + models, fetch in one call (the response is small — < 500 KB gzipped — and aggressively edge-cached). Filter and paginate in your client. This is intentional: server-side pagination of a fully-cacheable resource is wasteful for both of us.

Roadmap: cursor-based

When the dataset crosses 10 000 rows for any single resource we'll add cursor-based pagination using ?after=<cursor> and a X-Next-Cursor response header. The limit parameter will continue to work; cursors are additive. We'll announce in the changelog and add a Deprecation header to legacy unbounded calls six months in advance — typical breaking-change handling. See Versioning.

When to use bulk export instead

If you genuinely need everything, don't loop the list endpoints. Use GET /v1/export.json: one request, full snapshot, 24-hour cache header, costs you 1 request against your monthly quota. Pro tier and above.