---
title: "Get the benchmark leaderboard"
method: GET
path: "/v1/benchmark/leaderboard"
tags: ["Benchmark"]
---

# Get the benchmark leaderboard

`GET /v1/benchmark/leaderboard`

## Request

- Base URL: `https://api.roark.ai`
- URL: `https://api.roark.ai/v1/benchmark/leaderboard`
- Auth: HTTP bearer

Returns one ranked page of a suite version’s published targets, each with the metric cells it is judged on. Ranking happens in the database, so paging through the board is consistent. Every default the server applies (suite version, condition, sort metric, sort direction) is echoed on the response, so a page can be cited without guessing how it was ordered.

## Query parameters

- `suite` string, required
- `suiteVersion` string
- `conditionKey` string
- `sortBy` string
- `order` 'asc' | 'desc'
- `metrics` string: Comma-separated metric keys to project per row. Defaults to the headline set.
- `limit` integer: Maximum number of records to return (default: 20, max: 100)
- `offset` integer: Pagination offset

## Response `200`

One ranked page of the leaderboard

- object
  - `data` BenchmarkLeaderboardRow[], required
    - `target` BenchmarkTarget, required: A model or stack with a published result on a benchmark suite
      - `targetKey` string, required: Stable identity of the model/stack across sweeps. Cite this, and pass it to the target endpoints.
      - `targetName` string, required: Human-readable name of the model/stack.
      - `suite` string, required
      - `suiteVersion` string, required
      - `publicationId` string, uuid, required: Id of this one sweep. Changes every time the target is re-published, so it is a render key, not an identity.
      - `iterations` integer, required: Calls the sweep requested per condition.
      - `sampleCallCount` integer, required: Executed calls that contributed at least one score to these numbers.
      - `publishedAt` string, required: When this sweep was published (ISO-8601), i.e. data freshness.
      - `supersededAt` string, nullable, required: When a later sweep replaced this one. Null means it is the current generation.
      - `isCurrent` boolean, required: Whether these are the numbers Roark publishes for this target today.
    - `metrics` BenchmarkResult[], required: The projected cells for this row, measured under the requested condition.
      - `conditionKey` string, required: What these numbers were measured under: from suite v1.3 an industry scenario (`healthcare`, `home-services`, `insurance`, `customer-support`), before that a flow variant. The empty string is the overall rollup across all conditions.
      - `conditionLabel` string, required
      - `metricKey` string, required: Stable metric id, e.g. `response_time`.
      - `metricName` string, required
      - `metricKind` 'NUMERIC' | 'BOOLEAN', required: Which statistics are populated on a result. NUMERIC fills p50/p95/mean/ci; BOOLEAN fills passRate and its interval.
      - `unitSymbol` string, nullable, required: Display unit for numeric metrics, e.g. `ms`.
      - `n` integer, required: Scored samples behind this aggregate.
      - `p50` number, nullable, required
      - `p95` number, nullable, required
      - `mean` number, nullable, required
      - `ciLow` number, nullable, required: Low bound of the 95% CI of the mean (NUMERIC metrics).
      - `ciHigh` number, nullable, required
      - `passRate` number, nullable, required: Fraction passed, 0..1 (BOOLEAN metrics).
      - `passRateCiLow` number, nullable, required: Low bound of the 95% Wilson interval on the pass rate.
      - `passRateCiHigh` number, nullable, required
  - `suite` string, required
  - `suiteVersion` string, required: The version actually read, after defaulting.
  - `conditionKey` string, required
  - `sortedBy` BenchmarkSortDescriptor, required: The ranking this page was produced under
    - `metricKey` string, required
    - `order` 'asc' | 'desc', required
  - `pagination` BenchmarkPagination, required
    - `limit` integer, required
    - `offset` integer, required
    - `total` integer, required: Total matching records, ignoring this page.
    - `hasMore` boolean, required

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `404`: Not Found
- `500`: Internal Server Error

## Changes

> 188 revisions in range; 1 not diffed.

- **2026-09-15** `38989bd64cb3`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/roarkhq/apis/roark-analytics-api/changes/v1/benchmark/leaderboard/get.md)

---

[API](https://skmtc.dev/roarkhq/apis/roark-analytics-api.md) - [All operations](https://skmtc.dev/roarkhq/apis/roark-analytics-api/llms.txt) - [OpenAPI document](https://skmtc.dev/roarkhq/apis/roark-analytics-api/revisions/efc3377249d1?raw)