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

# Tournaments

> Compete in forecasting competitions with prizes and recognition

## Overview

Tournaments are time-bound forecasting competitions on Metaculus where participants compete for prizes and recognition. They provide a structured way to test forecasting skills on curated question sets.

## Tournament Structure

Tournaments are implemented as a special type of Project (from `projects/models.py:213-223`):

```python theme={null}
class ProjectTypes(models.TextChoices):
    TOURNAMENT = "tournament"
    QUESTION_SERIES = "question_series"
    INDEX = "index"
    # ... other types
```

<Info>
  **Question Series** are similar to tournaments but typically without prizes and more focused on tracking predictions over time on a specific topic.
</Info>

## Key Tournament Fields

From `projects/models.py:286-311`, tournaments have specific time and prize configuration:

```python theme={null}
class Project(TimeStampedModel, TranslatedModel):
    type = models.CharField(max_length=32, choices=ProjectTypes.choices)
    
    # Tournament-specific fields
    prize_pool = models.DecimalField(
        default=None,
        decimal_places=2,
        max_digits=15,
        null=True,
        blank=True
    )
    
    start_date = models.DateTimeField(null=True, blank=True)
    
    close_date = models.DateTimeField(
        help_text=(
            "The date the tournament wraps up and prizes will be paid. "
            "All questions that should be included in the leaderboard must "
            "close and resolve before this date. "
            "This is displayed on the front end as the 'Winners announced date'"
        ),
    )
    
    forecasting_end_date = models.DateTimeField(
        help_text=(
            "The date the last scored question that counts for the tournament closes. "
            "The date shown is the latest of the Forecasting end date "
            "and the latest question close date closing and resolving before the Close date."
        ),
    )
    
    sign_up_fields = models.JSONField(
        default=list,
        blank=True,
        help_text="Used during tournament onboarding."
    )
```

## Tournament Lifecycle

<Steps>
  <Step title="Announcement">
    Tournament is announced with rules, prize pool, and timeline. Type is set to `TOURNAMENT`.
  </Step>

  <Step title="Open for Forecasting">
    Questions become available between `start_date` and `forecasting_end_date`. Participants make predictions.
  </Step>

  <Step title="Forecasting Ends">
    Last question closes at `forecasting_end_date`. No more predictions accepted.
  </Step>

  <Step title="Resolution Period">
    Questions are resolved as outcomes become known. Must complete before `close_date`.
  </Step>

  <Step title="Winners Announced">
    Final scores calculated at `close_date`. Prize distribution announced.
  </Step>
</Steps>

### Tournament Status

From `projects/models.py:441-448`, tournaments have an `is_ongoing` property:

```python theme={null}
@property
def is_ongoing(self):
    if self.type in (
        self.ProjectTypes.TOURNAMENT,
        self.ProjectTypes.QUESTION_SERIES,
        self.ProjectTypes.INDEX,
    ):
        return self.close_date > django_timezone.now() if self.close_date else True
```

## Tournament Questions

Questions are associated with tournaments through the post-project relationship:

### Primary Association

From `projects/models.py:249-259`:

```python theme={null}
post = models.ForeignKey(
    "posts.Post",
    on_delete=models.CASCADE,
    related_name="questions",
)

# Post has:
default_project = models.ForeignKey(Project, on_delete=models.CASCADE)
projects = models.ManyToManyField(Project, related_name="posts")
```

Questions can be:

* **Primary to the tournament**: `post.default_project = tournament`
* **Tagged to the tournament**: Tournament in `post.projects`

## Leaderboards

Each tournament has a primary leaderboard that ranks participants.

### Primary Leaderboard

From `projects/models.py:240-246`:

```python theme={null}
primary_leaderboard = models.ForeignKey(
    "scoring.Leaderboard",
    null=True,
    on_delete=models.SET_NULL,
    related_name="primary_project",
    blank=True,
)
```

### Auto-Created Leaderboard

Tournaments automatically get a default leaderboard on creation (from `projects/models.py:422-439`):

```python theme={null}
def save(self, *args, **kwargs):
    creating = not self.pk
    super().save(*args, **kwargs)
    
    if creating and not self.primary_leaderboard and self.type in (
        self.ProjectTypes.TOURNAMENT,
        self.ProjectTypes.QUESTION_SERIES,
        self.ProjectTypes.COMMUNITY,
    ):
        from scoring.models import Leaderboard
        
        leaderboard = Leaderboard.objects.create(
            project=self,
            score_type=LeaderboardScoreTypes.PEER_TOURNAMENT,
        )
        Project.objects.filter(pk=self.pk).update(primary_leaderboard=leaderboard)
```

<Tip>
  The default leaderboard uses `PEER_TOURNAMENT` scoring, which sums peer scores across all tournament questions.
</Tip>

## Prize Pools

### Tournament Prize Pool

The main prize pool for the tournament (from `projects/models.py:287-289`):

```python theme={null}
prize_pool = models.DecimalField(
    default=None, decimal_places=2, max_digits=15, null=True, blank=True
)
```

### Leaderboard-Specific Prizes

Tournaments can have multiple leaderboards with different prize allocations (from `scoring/models.py:184-201`):

```python theme={null}
class Leaderboard(TimeStampedModel):
    prize_pool = models.DecimalField(
        help_text="""Optional. If not set, the Project's prize_pool will be used.
        If the Project has a prize pool, but this leaderboard has none, set this to 0.
        """,
    )
    
    minimum_prize_amount = models.DecimalField(
        default=50.00,
        decimal_places=2,
        max_digits=15,
        help_text="""The minimum amount a user can win in this leaderboard.
        Any remaining money is redistributed. Tournaments that close before June 2025
        will have a value of 0.00.
        """,
    )
```

<Warning>
  Prizes are typically distributed to top performers. The exact distribution formula depends on tournament rules and leaderboard configuration.
</Warning>

## Tournament Participation

### Sign-Up Fields

Tournaments can require custom sign-up information (from `projects/models.py:309-311`):

```python theme={null}
sign_up_fields = models.JSONField(
    default=list, blank=True, help_text="Used during tournament onboarding."
)
```

**Example sign-up fields**:

```json theme={null}
[
  {"field": "affiliation", "label": "University or Organization", "required": true},
  {"field": "experience", "label": "Forecasting Experience", "required": false}
]
```

### Follower Tracking

Tournaments track participant engagement (from `projects/models.py:375-379`):

```python theme={null}
followers_count = models.PositiveIntegerField(
    default=0, db_index=True, editable=False
)
forecasts_count = models.PositiveIntegerField(default=0, editable=False)
forecasters_count = models.PositiveIntegerField(default=0, editable=False)
```

## Bot Participation

Tournaments can control how bots participate in leaderboards.

### Bot Leaderboard Status

From `projects/models.py:248-264`:

```python theme={null}
class BotLeaderboardStatus(models.TextChoices):
    EXCLUDE_AND_HIDE = "exclude_and_hide"
    EXCLUDE_AND_SHOW = "exclude_and_show"
    INCLUDE = "include"
    BOTS_ONLY = "bots_only"

bot_leaderboard_status = models.CharField(
    max_length=32,
    choices=BotLeaderboardStatus.choices,
    default=BotLeaderboardStatus.EXCLUDE_AND_SHOW,
    help_text="""Sets the status of bots in any leaderboard associated with this project.
    exclude_and_hide: Bots excluded from ranks/prizes/medals and hidden from leaderboard.
    exclude_and_show: Bots excluded from ranks/prizes/medals but shown on leaderboard.
    include: Bots included in ranks/prizes/medals and shown on leaderboard.
    bots_only: Only Bots included in ranks/prizes/medals. Non-bots still shown.
    """,
)
```

<Tabs>
  <Tab title="Exclude & Hide">
    Bots don't appear on the leaderboard at all. Used when bots would be distracting.
  </Tab>

  <Tab title="Exclude & Show">
    **Default setting**. Bots appear on leaderboard for reference but don't compete for prizes. Useful for benchmarking.
  </Tab>

  <Tab title="Include">
    Bots compete alongside humans for ranks and prizes. Rarely used.
  </Tab>

  <Tab title="Bots Only">
    Only bots compete for prizes. Humans can participate but don't rank. Used for bot competitions.
  </Tab>
</Tabs>

## Visibility and Discovery

Tournaments control their visibility across the platform.

### Visibility Settings

From `projects/models.py:229-362`:

```python theme={null}
class Visibility(models.TextChoices):
    NORMAL = "normal"
    NOT_IN_MAIN_FEED = "not_in_main_feed"
    UNLISTED = "unlisted"

visibility = models.CharField(
    choices=Visibility.choices,
    default=Visibility.NOT_IN_MAIN_FEED,
    help_text=(
        "Sets the visibility of this project:\n"
        "Normal: Visible on main feed, contributes to global leaderboards/medals, "
        "lists the project in tournaments/question series page.\n"
        "Not In Main Feed: Not visible in main feed but searchable, doesn't contribute "
        "to global leaderboards/medals, lists in tournaments page.\n"
        "Unlisted: Not visible in main feed, not searchable, doesn't contribute "
        "to global leaderboards/medals. Default for newly created Tournaments/Question Series."
    ),
)
```

### Homepage Display

From `projects/models.py:364-368`:

```python theme={null}
show_on_homepage = models.BooleanField(default=False, db_index=True)
show_on_services_page = models.BooleanField(
    default=False, db_index=True, help_text="Show project on the Services page."
)
```

<Info>
  New tournaments start as `UNLISTED` by default, allowing admins to populate questions before making them public.
</Info>

## Tournament Metadata

### Branding and Description

From `projects/models.py:266-279`:

```python theme={null}
name = models.CharField(max_length=200)
slug = models.CharField(max_length=200, validators=[validate_alpha_slug])
subtitle = models.CharField(max_length=255, blank=True, default="")
description = models.TextField(blank=True, default="")
header_image = models.ImageField(null=True, blank=True)
header_logo = models.ImageField(null=True, blank=True)
emoji = models.CharField(max_length=10, default="", blank=True)
```

### SEO Metadata

From `projects/models.py:313-319`:

```python theme={null}
html_metadata_json = models.JSONField(
    help_text="Custom JSON for HTML meta tags. Supported fields are: title, description",
    null=True,
    blank=True,
    default=None,
)
```

## Forecast Flow

Tournaments can use an optimized forecasting interface (from `projects/models.py:370-372`):

```python theme={null}
forecasts_flow_enabled = models.BooleanField(
    default=True, help_text="Enables new forecast flow for tournaments"
)
```

This provides a streamlined UI for quickly making predictions across many tournament questions.

## Permissions

Tournaments inherit the Projects permission system.

### Default Permission

From `projects/models.py:332-339`:

```python theme={null}
default_permission = models.CharField(
    choices=ObjectPermission.choices,
    null=True,
    blank=True,
    default=ObjectPermission.FORECASTER,
    db_index=True,
)
```

**Permission levels**:

* `null`: Private tournament (not accessible)
* `FORECASTER`: Can view and make predictions
* `CURATOR`: Can view, forecast, and help curate questions
* `ADMIN`: Full control over tournament

### Override Permissions

From `projects/models.py:340` and `498-513`:

```python theme={null}
override_permissions = models.ManyToManyField(User, through="ProjectUserPermission")

class ProjectUserPermission(TimeStampedModel):
    user = models.ForeignKey(User, on_delete=models.CASCADE)
    project = models.ForeignKey(Project, on_delete=models.CASCADE)
    permission = models.CharField(choices=ObjectPermission.choices)
```

Individual users can have permissions that override the default.

## Tournament Examples

<CardGroup cols={2}>
  <Card title="Quarterly Tournament" icon="calendar">
    3-month competition on current events with monthly question releases
  </Card>

  <Card title="Domain Tournament" icon="microscope">
    Focused competition on AI, climate, economics, or other specific domain
  </Card>

  <Card title="Beginner Tournament" icon="graduation-cap">
    Lower-difficulty questions designed for new forecasters
  </Card>

  <Card title="Rapid Resolution" icon="bolt">
    Short-term questions that resolve within days or weeks
  </Card>
</CardGroup>

## Best Practices

<AccordionGroup>
  <Accordion title="Forecast Early" icon="clock">
    Tournament scoring rewards coverage. Make initial forecasts on all questions early, even if they're rough estimates.
  </Accordion>

  <Accordion title="Track Updates" icon="bell">
    Subscribe to tournament updates to know when new questions are added or when important information emerges.
  </Accordion>

  <Accordion title="Focus on Your Edge" icon="bullseye">
    You don't need to be best at every question. Focus on questions where you have domain expertise.
  </Accordion>

  <Accordion title="Learn from Others" icon="users">
    Read comments from top forecasters to understand their reasoning and improve your own forecasts.
  </Accordion>

  <Accordion title="Calibrate Your Confidence" icon="balance-scale">
    Tournament success requires well-calibrated probabilities, not just correct directional predictions.
  </Accordion>
</AccordionGroup>

## API Reference

<Card title="Projects API" icon="code" href="/api/projects">
  Explore the full Projects/Tournaments API documentation
</Card>

## Related Topics

<CardGroup cols={2}>
  <Card title="Projects" icon="folder" href="/features/projects">
    Understand the broader project system
  </Card>

  <Card title="Leaderboards" icon="ranking-star" href="/features/leaderboards">
    Learn how tournament rankings work
  </Card>

  <Card title="Scoring" icon="trophy" href="/features/scoring">
    Understand how tournament scores are calculated
  </Card>

  <Card title="Questions" icon="circle-question" href="/features/questions">
    Learn about question types and structure
  </Card>
</CardGroup>