---
title: "Rank runs by a metric"
method: GET
path: "/api/runs/leaderboard"
tags: ["Runs"]
---

# Rank runs by a metric

`GET /api/runs/leaderboard`

## Request

- Base URL: `https://pluto-api.trainy.ai`
- URL: `https://pluto-api.trainy.ai/api/runs/leaderboard`
- Auth: HTTP bearer

Returns runs ranked by a metric aggregation (MIN, MAX, AVG, LAST, VARIANCE) using pre-computed metric summaries. Much faster than comparing individual runs. Useful for finding the best runs in a project by loss, accuracy, or any other metric.

## Query parameters

- `projectName` string, required: Project name
- `logName` string, required: Metric name to rank by (e.g., 'train/loss', 'eval/accuracy')
- `aggregation` 'MIN' | 'MAX' | 'AVG' | 'LAST' | 'VARIANCE': Aggregation type: MIN, MAX, AVG, LAST, VARIANCE (default: LAST)
- `direction` 'ASC' | 'DESC': Sort direction: ASC (lowest first) or DESC (highest first). Default: ASC
- `limit` number, nullable: Number of runs to return (default: 20, max: 100)
- `offset` number, nullable: Offset for pagination (default: 0)

## Response `200`

Ranked list of runs with metric values

- LeaderboardResponse
  - `projectName` string, required
  - `logName` string, required
  - `aggregation` string, required
  - `direction` string, required
  - `runs` object[], required
    - `rank` number, required: 1-based rank position
    - `runId` number, required
    - `runName` string, required
    - `status` string, required
    - `url` string, required: URL to view this run in the UI
    - `value` number, required: The aggregated metric value used for ranking
    - `config` unknown
    - `tags` string[], required
    - `createdAt` string, required
  - `total` number, required: Total number of runs that have this metric

---

[API](https://skmtc.dev/trainy/apis/mlop-api.md) - [All operations](https://skmtc.dev/trainy/apis/mlop-api/llms.txt) - [OpenAPI document](https://skmtc.dev/trainy/apis/mlop-api/revisions/5d2c0b0baecb?raw)