> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trainy.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Rank runs by a metric

> 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.



## OpenAPI

````yaml /pluto/api-reference/openapi.json get /api/runs/leaderboard
openapi: 3.0.0
info:
  title: mlop API
  version: 1.0.0
  description: API for mlop - ML experiment tracking platform
servers:
  - url: https://pluto-api.trainy.ai
    description: API Server
security:
  - bearerAuth: []
paths:
  /api/runs/leaderboard:
    get:
      tags:
        - Runs
      summary: Rank runs by a metric
      description: >-
        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.
      parameters:
        - schema:
            type: string
            description: Project name
          required: true
          name: projectName
          in: query
        - schema:
            type: string
            description: Metric name to rank by (e.g., 'train/loss', 'eval/accuracy')
          required: true
          name: logName
          in: query
        - schema:
            type: string
            enum:
              - MIN
              - MAX
              - AVG
              - LAST
              - VARIANCE
            default: LAST
            description: 'Aggregation type: MIN, MAX, AVG, LAST, VARIANCE (default: LAST)'
          required: false
          name: aggregation
          in: query
        - schema:
            type: string
            enum:
              - ASC
              - DESC
            default: ASC
            description: >-
              Sort direction: ASC (lowest first) or DESC (highest first).
              Default: ASC
          required: false
          name: direction
          in: query
        - schema:
            type: number
            nullable: true
            default: 20
            description: 'Number of runs to return (default: 20, max: 100)'
          required: false
          name: limit
          in: query
        - schema:
            type: number
            nullable: true
            default: 0
            description: 'Offset for pagination (default: 0)'
          required: false
          name: offset
          in: query
      responses:
        '200':
          description: Ranked list of runs with metric values
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeaderboardResponse'
      security:
        - bearerAuth: []
components:
  schemas:
    LeaderboardResponse:
      type: object
      properties:
        projectName:
          type: string
        logName:
          type: string
        aggregation:
          type: string
        direction:
          type: string
        runs:
          type: array
          items:
            type: object
            properties:
              rank:
                type: number
                description: 1-based rank position
              runId:
                type: number
              runName:
                type: string
              status:
                type: string
              url:
                type: string
                description: URL to view this run in the UI
              value:
                type: number
                description: The aggregated metric value used for ranking
              config:
                nullable: true
              tags:
                type: array
                items:
                  type: string
              createdAt:
                type: string
            required:
              - rank
              - runId
              - runName
              - status
              - url
              - value
              - tags
              - createdAt
        total:
          type: number
          description: Total number of runs that have this metric
      required:
        - projectName
        - logName
        - aggregation
        - direction
        - runs
        - total
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: API key obtained from the mlop dashboard

````