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

# Projects

> Access tournaments, categories, and communities

## Overview

Projects in Metaculus organize questions into curated collections. There are several types:

* **Tournaments** - Competitive forecasting events with leaderboards and prizes
* **Categories** - Topic-based groupings (e.g., "Health & Pandemics", "AI")
* **Topics** - High-level thematic areas
* **Communities** - User-created private or public question collections
* **Site Main** - The main Metaculus community

Projects are used to filter posts and track specialized leaderboards.

***

## List Tournaments

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

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

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

`GET /api/projects/tournaments/`

Retrieve a list of all active tournaments.

### Response

<ResponseField name="results" type="array">
  Array of tournament objects
</ResponseField>

### Tournament Object

<ResponseField name="id" type="integer">
  Unique tournament identifier
</ResponseField>

<ResponseField name="type" type="string">
  Always `"tournament"`
</ResponseField>

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

<ResponseField name="slug" type="string">
  URL-friendly slug used in filters
</ResponseField>

<ResponseField name="prize_pool" type="string">
  Total prize pool amount
</ResponseField>

<ResponseField name="start_date" type="string (datetime)">
  When the tournament starts
</ResponseField>

<ResponseField name="close_date" type="string (datetime)">
  When the tournament ends
</ResponseField>

<ResponseField name="is_ongoing" type="boolean">
  Whether the tournament is currently active
</ResponseField>

<ResponseField name="user_permission" type="string">
  Current user's permission: `forecaster` or `viewer`
</ResponseField>

<ResponseField name="default_permission" type="string">
  Default permission for new users
</ResponseField>

<ResponseField name="visibility" type="string">
  Visibility level: `normal`, `not_in_main_feed`, or `unlisted`
</ResponseField>

***

## Get Tournament by Slug

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

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

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

`GET /api/projects/tournaments/{slug}/`

Retrieve detailed information about a specific tournament.

### Path Parameters

<ParamField path="slug" type="string" required>
  The tournament slug
</ParamField>

***

## List Categories

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

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

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

`GET /api/projects/categories/`

Retrieve all available categories.

### Response

<ResponseField name="results" type="array">
  Array of category objects
</ResponseField>

### Category Object

<ResponseField name="id" type="integer">
  Unique category identifier
</ResponseField>

<ResponseField name="name" type="string">
  Category name (e.g., "Health & Pandemics")
</ResponseField>

<ResponseField name="slug" type="string">
  URL-friendly slug (e.g., "health-pandemics")
</ResponseField>

<ResponseField name="description" type="string">
  Category description
</ResponseField>

***

## List Topics

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

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

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

`GET /api/projects/topics/`

Retrieve all available topics.

### Response

<ResponseField name="results" type="array">
  Array of topic objects
</ResponseField>

### Topic Object

<ResponseField name="id" type="integer">
  Unique topic identifier
</ResponseField>

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

<ResponseField name="slug" type="string">
  URL-friendly slug
</ResponseField>

<ResponseField name="emoji" type="string">
  Emoji icon for the topic
</ResponseField>

<ResponseField name="section" type="string">
  Section this topic belongs to
</ResponseField>

***

## List Communities

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

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

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

`GET /api/projects/communities/`

Retrieve all communities visible to the current user.

### Response

Returns array of project objects with `type: "community"`.

***

## Get Community by Slug

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

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

  response = requests.get(
      "https://www.metaculus.com/api/projects/communities/my-community/",
      headers={"Authorization": "Token YOUR_TOKEN"}
  )
  print(response.json())
  ```
</CodeGroup>

`GET /api/projects/communities/{slug}/`

Retrieve detailed information about a specific community.

### Path Parameters

<ParamField path="slug" type="string" required>
  The community slug
</ParamField>

***

## Get Project Members

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

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

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

`GET /api/projects/{projectId}/members/`

Retrieve members of a project (typically used for communities and tournaments).

### Path Parameters

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

### Response

<ResponseField name="results" type="array">
  Array of member objects

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

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

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

  <ResponseField name="permission" type="string">
    User's permission level in this project
  </ResponseField>

  <ResponseField name="role" type="string">
    User's role (e.g., "admin", "member")
  </ResponseField>
</ResponseField>

***

## Subscribe to Project

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

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

  response = requests.post(
      "https://www.metaculus.com/api/projects/144/subscribe/",
      headers={"Authorization": "Token YOUR_TOKEN"}
  )
  print(response.status_code)
  ```
</CodeGroup>

`POST /api/projects/{projectId}/subscribe/`

Subscribe to notifications from a project.

### Path Parameters

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

***

## Unsubscribe from Project

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

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

  response = requests.post(
      "https://www.metaculus.com/api/projects/144/unsubscribe/",
      headers={"Authorization": "Token YOUR_TOKEN"}
  )
  print(response.status_code)
  ```
</CodeGroup>

`POST /api/projects/{projectId}/unsubscribe/`

Unsubscribe from project notifications.

### Path Parameters

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

***

## Download Project Data

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://www.metaculus.com/api/projects/144/download-data/?include_scores=true" \
    -H "Authorization: Token YOUR_TOKEN" \
    --output project_data.zip
  ```

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

  response = requests.get(
      "https://www.metaculus.com/api/projects/144/download-data/",
      headers={"Authorization": "Token YOUR_TOKEN"},
      params={"include_scores": True}
  )

  with open("project_data.zip", "wb") as f:
      f.write(response.content)
  ```
</CodeGroup>

`GET /api/projects/{projectId}/download-data/`

Download all question and forecast data for a project as a ZIP file containing CSVs.

### Path Parameters

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

### Query Parameters

<ParamField query="include_comments" type="boolean" default="false">
  Include comment data in the export
</ParamField>

<ParamField query="include_scores" type="boolean" default="false">
  Include scoring data in the export
</ParamField>

### Response

Returns a ZIP file containing:

* `question_data.csv` - Question metadata
* `forecast_data.csv` - All forecasts and aggregations
* `comment_data.csv` - Comments (if requested)
* `score_data.csv` - Scores (if requested)
* `README.txt` - Data dictionary

<Note>
  **Access Restrictions**

  Full project data downloads are only available to:

  * Site administrators
  * Project administrators
  * Whitelisted users

  Contact Metaculus if you need bulk data access for research purposes.
</Note>

***

## Get Site Main Project

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

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

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

`GET /api/projects/site_main/`

Retrieve information about the main Metaculus community project.

***

## Usage Examples

### Filter Posts by Tournament

```python theme={null}
import requests

# Get all open questions in the AI Benchmarking tournament
response = requests.get(
    "https://www.metaculus.com/api/posts/",
    headers={"Authorization": "Token YOUR_TOKEN"},
    params={
        "tournaments": "aibq4",
        "statuses": "open",
        "limit": 50
    }
)

for post in response.json()["results"]:
    print(f"{post['title']} - {post['nr_forecasters']} forecasters")
```

### Filter Posts by Category

```python theme={null}
import requests

# Get recent AI questions
response = requests.get(
    "https://www.metaculus.com/api/posts/",
    headers={"Authorization": "Token YOUR_TOKEN"},
    params={
        "categories": "artificial-intelligence",
        "order_by": "-published_at",
        "limit": 20
    }
)

for post in response.json()["results"]:
    print(f"{post['title']}")
```