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

# Leaderboards

> Access forecasting leaderboards and rankings

## Overview

Leaderboards track forecaster performance across the platform and within specific tournaments. Metaculus uses sophisticated scoring algorithms to measure forecast accuracy and reward skilled predictors.

***

## Get Global Leaderboard

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://www.metaculus.com/api/leaderboards/global/?limit=50" \
    -H "Authorization: Token YOUR_TOKEN"
  ```

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

  response = requests.get(
      "https://www.metaculus.com/api/leaderboards/global/",
      headers={"Authorization": "Token YOUR_TOKEN"},
      params={"limit": 50}
  )
  leaderboard = response.json()

  for entry in leaderboard["entries"][:10]:
      user = entry["user"]
      print(f"{entry['rank']}. {user['username']}: {entry['score']:.2f} points")
  ```
</CodeGroup>

`GET /api/leaderboards/global/`

Retrieve the global Metaculus leaderboard showing top forecasters across all questions.

### Query Parameters

<ParamField query="for_user" type="integer">
  Show leaderboard position for a specific user
</ParamField>

<ParamField query="score_type" type="string">
  Score type to display: `peer`, `baseline`, `spot_peer`, `spot_baseline`
</ParamField>

<ParamField query="limit" type="integer" default="50">
  Number of entries to return
</ParamField>

<ParamField query="offset" type="integer" default="0">
  Pagination offset
</ParamField>

### Response

<ResponseField name="leaderboard" type="object">
  Leaderboard metadata

  <ResponseField name="id" type="integer">
    Leaderboard ID
  </ResponseField>

  <ResponseField name="name" type="string">
    Leaderboard name
  </ResponseField>

  <ResponseField name="score_type" type="string">
    Scoring method used
  </ResponseField>

  <ResponseField name="start_time" type="string (datetime)">
    When this leaderboard period started
  </ResponseField>

  <ResponseField name="end_time" type="string (datetime)">
    When this leaderboard period ends
  </ResponseField>

  <ResponseField name="finalized" type="boolean">
    Whether the leaderboard is finalized
  </ResponseField>
</ResponseField>

<ResponseField name="entries" type="array">
  Array of leaderboard entry objects
</ResponseField>

### Leaderboard Entry Object

<ResponseField name="user" type="object">
  User information

  <ResponseField name="id" type="integer">
    User ID
  </ResponseField>

  <ResponseField name="username" type="string">
    Username
  </ResponseField>

  <ResponseField name="is_bot" type="boolean">
    Whether this is a bot account
  </ResponseField>
</ResponseField>

<ResponseField name="rank" type="integer">
  Position on the leaderboard (1 = first place)
</ResponseField>

<ResponseField name="score" type="number">
  Total forecasting score
</ResponseField>

<ResponseField name="ci_lower" type="number">
  Lower bound of 95% confidence interval for score
</ResponseField>

<ResponseField name="ci_upper" type="number">
  Upper bound of 95% confidence interval for score
</ResponseField>

<ResponseField name="coverage" type="number">
  Proportion of scored questions the user forecasted (0-1)
</ResponseField>

<ResponseField name="contribution_count" type="integer">
  Number of questions contributing to this score
</ResponseField>

<ResponseField name="medal" type="string">
  Medal earned: `gold`, `silver`, `bronze`, or null
</ResponseField>

<ResponseField name="prize" type="number">
  Prize amount earned (for tournaments)
</ResponseField>

<ResponseField name="excluded" type="boolean">
  Whether this entry is excluded from rankings
</ResponseField>

***

## Get Project Leaderboard

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://www.metaculus.com/api/leaderboards/project/144/" \
    -H "Authorization: Token YOUR_TOKEN"
  ```

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

  response = requests.get(
      "https://www.metaculus.com/api/leaderboards/project/144/",
      headers={"Authorization": "Token YOUR_TOKEN"}
  )
  print(response.json())
  ```
</CodeGroup>

`GET /api/leaderboards/project/{projectId}/`

Retrieve the leaderboard for a specific project or tournament.

### Path Parameters

<ParamField path="projectId" type="integer" required>
  The project ID
</ParamField>

### Query Parameters

Same as global leaderboard, plus:

<ParamField query="primary_only" type="boolean" default="false">
  Only show the primary leaderboard for this project
</ParamField>

### Response

Returns the same structure as the global leaderboard, but includes additional fields:

<ResponseField name="leaderboard.project_id" type="integer">
  The project this leaderboard belongs to
</ResponseField>

<ResponseField name="leaderboard.project_name" type="string">
  Project name
</ResponseField>

<ResponseField name="leaderboard.project_slug" type="string">
  Project slug
</ResponseField>

<ResponseField name="leaderboard.prize_pool" type="string">
  Total prize pool for this tournament
</ResponseField>

<ResponseField name="leaderboard.is_primary_leaderboard" type="boolean">
  Whether this is the project's primary leaderboard
</ResponseField>

<ResponseField name="entries[].take" type="number">
  For tournaments: user's tournament-specific score
</ResponseField>

<ResponseField name="entries[].percent_prize" type="number">
  For tournaments: percentage of prize pool won
</ResponseField>

***

## Get User Medals

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://www.metaculus.com/api/medals/?user_id=12345" \
    -H "Authorization: Token YOUR_TOKEN"
  ```

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

  response = requests.get(
      "https://www.metaculus.com/api/medals/",
      headers={"Authorization": "Token YOUR_TOKEN"},
      params={"user_id": 12345}
  )
  medals = response.json()

  print(f"Gold medals: {medals['gold']}")
  print(f"Silver medals: {medals['silver']}")
  print(f"Bronze medals: {medals['bronze']}")
  ```
</CodeGroup>

`GET /api/medals/`

Retrieve medal counts for a user.

### Query Parameters

<ParamField query="user_id" type="integer" required>
  User ID to get medals for
</ParamField>

### Response

<ResponseField name="gold" type="integer">
  Number of gold medals
</ResponseField>

<ResponseField name="silver" type="integer">
  Number of silver medals
</ResponseField>

<ResponseField name="bronze" type="integer">
  Number of bronze medals
</ResponseField>

<ResponseField name="tournaments" type="array">
  List of tournaments where medals were earned

  <ResponseField name="project_id" type="integer">
    Tournament project ID
  </ResponseField>

  <ResponseField name="project_name" type="string">
    Tournament name
  </ResponseField>

  <ResponseField name="medal" type="string">
    Medal type earned
  </ResponseField>

  <ResponseField name="rank" type="integer">
    Final rank in tournament
  </ResponseField>
</ResponseField>

***

## Get Metaculus Track Record

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://www.metaculus.com/api/metaculus_track_record/" \
    -H "Authorization: Token YOUR_TOKEN"
  ```

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

  response = requests.get(
      "https://www.metaculus.com/api/metaculus_track_record/",
      headers={"Authorization": "Token YOUR_TOKEN"}
  )
  track_record = response.json()

  for stat in track_record["statistics"]:
      print(f"{stat['name']}: {stat['value']}")
  ```
</CodeGroup>

`GET /api/metaculus_track_record/`

Retrieve Metaculus's overall forecasting track record and performance statistics.

### Response

<ResponseField name="statistics" type="array">
  Array of platform-wide statistics

  <ResponseField name="name" type="string">
    Statistic name
  </ResponseField>

  <ResponseField name="value" type="number">
    Statistic value
  </ResponseField>

  <ResponseField name="description" type="string">
    What this statistic measures
  </ResponseField>
</ResponseField>

<ResponseField name="calibration_data" type="object">
  Calibration curve data showing how often predictions match outcomes
</ResponseField>

***

## Understanding Score Types

<Note>
  **Peer Score vs Baseline Score**

  Metaculus uses multiple scoring methods:

  * **Peer Score**: Measures performance relative to the community aggregate
  * **Baseline Score**: Measures performance relative to a baseline prior
  * **Spot Score**: Evaluated at a specific time (CP reveal time) rather than continuously

  Higher scores are better. Scores can be negative if predictions are worse than the baseline.
</Note>

### Score Calculation

Scores are calculated using:

1. **Log Score**: Rewards accuracy with proper scoring rules
2. **Coverage**: Weights scores by how many questions you forecasted
3. **Recency**: More recent forecasts may have higher weight

***

## Example: Tournament Rankings

```python theme={null}
import requests

headers = {"Authorization": "Token YOUR_TOKEN"}

# Get tournament leaderboard
response = requests.get(
    "https://www.metaculus.com/api/leaderboards/project/3876/",
    headers=headers,
    params={"limit": 10}
)

leaderboard = response.json()
project = leaderboard["leaderboard"]

print(f"Tournament: {project['project_name']}")
print(f"Prize Pool: ${project['prize_pool']}")
print(f"Status: {'Finalized' if project['finalized'] else 'Ongoing'}")
print("\nTop 10:")

for entry in leaderboard["entries"]:
    user = entry["user"]
    medal = f" 🏅{entry['medal']}" if entry["medal"] else ""
    prize = f" (${entry['prize']:.2f})" if entry.get("prize") else ""
    
    print(f"{entry['rank']:2d}. {user['username']:20s} "
          f"Score: {entry['score']:7.2f} "
          f"Coverage: {entry['coverage']:.1%}{medal}{prize}")
```

## Example: Compare User to Leaderboard

```python theme={null}
import requests

headers = {"Authorization": "Token YOUR_TOKEN"}
user_id = 12345

# Get user's position on global leaderboard
response = requests.get(
    "https://www.metaculus.com/api/leaderboards/global/",
    headers=headers,
    params={
        "for_user": user_id,
        "limit": 100
    }
)

leaderboard = response.json()
user_entry = next(
    (e for e in leaderboard["entries"] if e["user"]["id"] == user_id),
    None
)

if user_entry:
    print(f"Your rank: {user_entry['rank']}")
    print(f"Your score: {user_entry['score']:.2f}")
    print(f"Your coverage: {user_entry['coverage']:.1%}")
    print(f"Questions scored: {user_entry['contribution_count']}")
    
    # Compare to #1
    top_entry = leaderboard["entries"][0]
    score_diff = top_entry["score"] - user_entry["score"]
    print(f"\nGap to #1: {score_diff:.2f} points")
else:
    print("User not found on leaderboard")
```