metaculus

What this skill does

# Metaculus API

[Metaculus](https://www.metaculus.com) is a forecasting platform where users predict outcomes of real-world events. Questions range across science, technology, politics, economics, and more. The platform aggregates individual forecasts into community predictions and scores forecasters on accuracy.

Check this skill and the [official API documentation](https://www.metaculus.com/api/) _FREQUENTLY_ for updates.

> **Feedback:** Contact the Metaculus team at [[email protected]](mailto:[email protected]) with questions, ideas, or feedback.

> **Source code & issues:** [github.com/Metaculus/metaculus](https://github.com/Metaculus/metaculus/issues)

---

## Key Concepts (Glossary)

| Term | Definition |
|---|---|
| **Post** | The primary feed entity. A post wraps a question, group of questions, conditional pair, or notebook. Posts have statuses, authors, projects, and comments. |
| **Question** | A single forecastable item within a post. Types: `binary`, `multiple_choice`, `numeric`, `discrete`, `date`. |
| **Group of Questions** | A post containing multiple related sub-questions displayed together (e.g., "What will GDP be in 2025, 2026, 2027?"). |
| **Conditional** | A post with paired questions: "If [condition], what is P(child)?" — produces question_yes and question_no variants. |
| **Forecast** | A user's prediction on a question. Format depends on question type: probability (binary), CDF (continuous), or distribution (multiple choice). |
| **Community Prediction (CP)** | The aggregated forecast from all users, computed via various aggregation methods. |
| **Aggregation Method** | How individual forecasts are combined: `recency_weighted` (default), `unweighted`, `metaculus_prediction`, `single_aggregation`. |
| **Project** | A container for posts — can be a tournament, category, tag, question series, or site section. |
| **Tournament** | A special project type with prize pools, start/close dates, and leaderboards. |
| **Category** | A topic classification (e.g., "Nuclear Technology & Risks", "Health & Pandemics"). |
| **Resolution** | The actual outcome of a question once known. Values vary by type: `yes`/`no` (binary), a number, a date, or an option name. |
| **Curation Status** | Editorial status of a post: `draft`, `pending`, `rejected`, `approved`. |
| **Scaling** | Defines how a continuous question's range maps to the CDF. Includes `range_min`, `range_max`, `zero_point` (for log scale), and bounds. |
| **CDF** | Cumulative Distribution Function — the format for continuous forecasts. A list of 201 floats (or `inbound_outcome_count + 1` for discrete). |
| **Inbound Outcome Count** | Number of possible outcomes within a question's range (excluding out-of-bounds). Default is 200 for continuous; smaller for discrete. |

---

## Base URL

All endpoints are served from:

```
https://www.metaculus.com
```

All paths below are relative to this base (e.g., `GET /api/posts/` means `GET https://www.metaculus.com/api/posts/`).

---

## Authentication

**All API requests require authentication.** Unauthenticated requests are rejected.

### Getting Your Token

1. Log in to [Metaculus](https://www.metaculus.com).
2. Go to your [Account Settings → API Access](https://www.metaculus.com/accounts/settings/account/#api-access).
3. Copy (or generate) your API token.

### Using the Token

Add the `Authorization` header to every request. The token must be prefixed with the literal string `Token` followed by a space:

```
Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b
```

### Example: curl

```bash
curl -s "https://www.metaculus.com/api/posts/?limit=5&order_by=-published_at" \
  -H "Authorization: Token $METACULUS_API_TOKEN" | jq .
```

### Example: Python

```python
import os, requests

TOKEN = os.environ["METACULUS_API_TOKEN"]
HEADERS = {"Authorization": f"Token {TOKEN}"}
BASE = "https://www.metaculus.com"

resp = requests.get(f"{BASE}/api/posts/", headers=HEADERS, params={"limit": 5})
resp.raise_for_status()
data = resp.json()
```

### Environment Variables

Never hardcode tokens. Store them as environment variables or in a `.env` file:

```
METACULUS_API_TOKEN=your-token-here
```

---

## Rate Limits

Metaculus throttles requests to prevent abuse. If you receive a `429 Too Many Requests` response, implement exponential backoff before retrying.

---

## REST API Endpoints Overview

### Feed (Posts)

| Method | Endpoint | Description | Auth |
|---|---|---|---|
| `GET` | `/api/posts/` | Retrieve paginated posts feed with filters | Required |
| `GET` | `/api/posts/{postId}/` | Retrieve a single post with full details | Required |

### Questions & Forecasts

| Method | Endpoint | Description | Auth |
|---|---|---|---|
| `POST` | `/api/questions/forecast/` | Submit forecasts for one or more questions | Required |
| `POST` | `/api/questions/withdraw/` | Withdraw active forecasts | Required |

### Comments

| Method | Endpoint | Description | Auth |
|---|---|---|---|
| `GET` | `/api/comments/` | Retrieve comments (filter by post or author) | Required |
| `POST` | `/api/comments/create/` | Create a new comment on a post | Required |

### Utilities & Data

| Method | Endpoint | Description | Auth |
|---|---|---|---|
| `GET` | `/api/posts/{postId}/download-data/` | Download question data as a ZIP of CSVs | Required |
| `GET` | `/api/projects/{projectId}/download-data/` | Download full project data as a ZIP of CSVs | Required (admin/whitelisted) |

---

## Data Model

### Post → Question Hierarchy

A **Post** is the top-level entity in the feed. Each post contains exactly one of:

- `question` — a single question (binary, numeric, date, multiple choice, or discrete)
- `group_of_questions` — multiple related sub-questions
- `conditional` — a conditional pair (condition + child, producing question_yes and question_no)
- A notebook (no question content)

The other fields will be `null`. For example, a post with a single binary question will have `question` populated and `conditional`/`group_of_questions` set to `null`.

### Post

| Field | Type | Description |
|---|---|---|
| `id` | integer | Unique post ID |
| `title` | string | Full title |
| `short_title` | string | URL-friendly short title |
| `slug` | string | URL slug |
| `author_id` | integer | Author's user ID |
| `author_username` | string | Author's username |
| `projects` | object | Associated projects (see below) |
| `created_at` | datetime | When the post was created |
| `published_at` | datetime? | When the post was published |
| `open_time` | datetime? | When the question opened for forecasting |
| `edited_at` | datetime | Last edit timestamp |
| `curation_status` | string | `draft`, `pending`, `rejected`, or `approved` |
| `comment_count` | integer | Number of comments |
| `status` | string | `open`, `upcoming`, `closed`, `resolved`, `draft`, `pending`, `rejected` |
| `nr_forecasters` | integer | Number of unique forecasters |
| `question` | Question? | Single question (if applicable) |
| `conditional` | Conditional? | Conditional pair (if applicable) |
| `group_of_questions` | GroupOfQuestions? | Question group (if applicable) |
| `user_permission` | string | `forecaster` or `viewer` |
| `vote` | object | `{ score: int, user_vote: string? }` |
| `forecasts_count` | integer | Total number of forecasts |

### Post Projects Object

| Field | Type | Description |
|---|---|---|
| `site_main` | Project[] | Site-level project associations |
| `tournament` | Project[] | Tournaments this post belongs to |
| `category` | Category[] | Categories |
| `tag` | Tag[] | Tags |
| `question_series` | Project[] | Question series |
| `default_project` | Project | The post's primary/default project |

### Project

| Field | Type | Description |
|---|---|---|
| `id` | integer | Project ID |
| `type` | string | `site_main`, `tournament`, etc. |
| `name` | string | Display name |
| `slug` | string? | URL slug |
| `prize_pool` | string | Prize pool amount (e.g., "0.00") |
| `start_date` |