> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/open-webui/open-webui/llms.txt
> Use this file to discover all available pages before exploring further.

# Leaderboard

> Model evaluation leaderboard and history endpoints

## Get Leaderboard

<api method="GET" endpoint="/api/evaluations/leaderboard" />

Retrieve the model leaderboard with Elo ratings based on user feedback comparisons.

The leaderboard uses an Elo rating system where:

* Each model starts with a rating of 1000
* Ratings are adjusted based on head-to-head comparisons from user feedback
* The K-factor of 32 controls rating volatility
* Optional query-based filtering uses semantic similarity to weight relevant feedbacks

### Query Parameters

<ParamField query="query" type="string" optional>
  Filter leaderboard by tag similarity. When provided, uses semantic embeddings to compute relevance scores and weight the Elo calculations. This creates topic-specific leaderboards (e.g., "coding" shows which models perform best for coding tasks).
</ParamField>

### Response

<ResponseField name="entries" type="array">
  Array of leaderboard entries sorted by rating (highest first)

  <Expandable title="LeaderboardEntry properties">
    <ResponseField name="model_id" type="string">
      Unique identifier for the model
    </ResponseField>

    <ResponseField name="rating" type="integer">
      Elo rating rounded to nearest integer (base rating: 1000)
    </ResponseField>

    <ResponseField name="won" type="integer">
      Number of comparisons won against other models
    </ResponseField>

    <ResponseField name="lost" type="integer">
      Number of comparisons lost against other models
    </ResponseField>

    <ResponseField name="count" type="integer">
      Total number of comparisons (won + lost)
    </ResponseField>

    <ResponseField name="top_tags" type="array">
      Most frequent tags associated with this model's feedback

      <Expandable title="Tag properties">
        <ResponseField name="tag" type="string">
          Tag name
        </ResponseField>

        <ResponseField name="count" type="integer">
          Number of times this tag appears
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://your-instance.com/api/evaluations/leaderboard" \
    -H "Authorization: Bearer $OPENWEBUI_API_KEY"
  ```

  ```bash With Query Filter theme={null}
  curl -X GET "https://your-instance.com/api/evaluations/leaderboard?query=coding" \
    -H "Authorization: Bearer $OPENWEBUI_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://your-instance.com/api/evaluations/leaderboard",
      headers={"Authorization": f"Bearer {api_key}"}
  )
  leaderboard = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "entries": [
      {
        "model_id": "gpt-4",
        "rating": 1245,
        "won": 42,
        "lost": 18,
        "count": 60,
        "top_tags": [
          {"tag": "coding", "count": 25},
          {"tag": "reasoning", "count": 18},
          {"tag": "creative", "count": 12}
        ]
      },
      {
        "model_id": "claude-3",
        "rating": 1198,
        "won": 38,
        "lost": 22,
        "count": 60,
        "top_tags": [
          {"tag": "writing", "count": 30},
          {"tag": "analysis", "count": 15}
        ]
      }
    ]
  }
  ```
</ResponseExample>

***

## Get Model History

<api method="GET" endpoint="/api/evaluations/leaderboard/{model_id}/history" />

Retrieve the daily win/loss history for a specific model over a time period.

### Path Parameters

<ParamField path="model_id" type="string" required>
  Unique identifier for the model
</ParamField>

### Query Parameters

<ParamField query="days" type="integer" default="30">
  Number of days of history to retrieve (default: 30)
</ParamField>

### Response

<ResponseField name="model_id" type="string">
  Unique identifier for the model
</ResponseField>

<ResponseField name="history" type="array">
  Array of daily win/loss records

  <Expandable title="ModelHistoryEntry properties">
    <ResponseField name="date" type="string">
      Date in ISO 8601 format (YYYY-MM-DD)
    </ResponseField>

    <ResponseField name="won" type="integer">
      Number of comparisons won on this date
    </ResponseField>

    <ResponseField name="lost" type="integer">
      Number of comparisons lost on this date
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://your-instance.com/api/evaluations/leaderboard/gpt-4/history" \
    -H "Authorization: Bearer $OPENWEBUI_API_KEY"
  ```

  ```bash Custom Time Range theme={null}
  curl -X GET "https://your-instance.com/api/evaluations/leaderboard/gpt-4/history?days=7" \
    -H "Authorization: Bearer $OPENWEBUI_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://your-instance.com/api/evaluations/leaderboard/gpt-4/history",
      params={"days": 7},
      headers={"Authorization": f"Bearer {api_key}"}
  )
  history = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "model_id": "gpt-4",
    "history": [
      {
        "date": "2026-03-02",
        "won": 5,
        "lost": 2
      },
      {
        "date": "2026-03-01",
        "won": 8,
        "lost": 3
      },
      {
        "date": "2026-02-28",
        "won": 6,
        "lost": 4
      }
    ]
  }
  ```
</ResponseExample>