API Overview

Introduction to the Metaculus Forecasting Platform REST API

Welcome to the Metaculus API

The Metaculus API provides programmatic access to the Metaculus forecasting platform, allowing you to retrieve posts, questions, forecasts, comments, and submit your own predictions.

Base URL

All API requests should be made to:

https://www.metaculus.com/api/

API Version

The current API version is 2.0.0. The API follows semantic versioning principles.

Response Format

All API responses are returned in JSON format. The API uses standard HTTP response codes:

• 200 OK - Request succeeded
• 201 Created - Resource created successfully
• 400 Bad Request - Invalid request parameters
• 401 Unauthorized - Authentication required or invalid credentials
• 403 Forbidden - Authenticated but not authorized for this resource
• 404 Not Found - Resource not found
• 429 Too Many Requests - Rate limit exceeded
• 500 Internal Server Error - Server error

Successful Response Structure

Most list endpoints return paginated results with the following structure:

{
  "next": "https://www.metaculus.com/api/posts/?limit=20&offset=20",
  "previous": null,
  "results": [
    // Array of resources
  ]
}

Error Response Structure

Error responses include a descriptive message:

{
  "detail": "Authentication credentials were not provided."
}

Pagination

The API uses limit-offset pagination:

• limit - Number of results per page (default: 20, max: 100)
• offset - Number of results to skip

Example:

curl "https://www.metaculus.com/api/posts/?limit=50&offset=100" \
  -H "Authorization: Token YOUR_API_TOKEN"

Data Model

The Metaculus API is built around these core concepts:

Posts

Posts are the primary content units on Metaculus. Each post can contain:

• Individual questions (binary, multiple choice, numeric, date)
• Groups of questions
• Conditional question pairs
• Notebooks

Questions

Questions are the forecasting targets within posts. Supported types:

• binary - Yes/No questions
• multiple_choice - Questions with multiple discrete options
• numeric - Continuous numeric predictions
• date - Date-based predictions
• discrete - Discrete numeric values

Forecasts

Forecasts are predictions submitted by users on questions. Each question type has its own forecast format.

Getting Started

To start using the API:

1. Create a Metaculus account at metaculus.com
2. Generate an API token from your account settings
3. Include the token in your requests using the Authorization header
4. Start making API requests!

All API requests require valid authentication credentials. Unauthenticated requests will be rejected.

Quick Example

Here’s a simple example to retrieve recent posts:

cURL

curl "https://www.metaculus.com/api/posts/?limit=5" \
  -H "Authorization: Token YOUR_API_TOKEN"

Support and Feedback

We’re continuously improving the API and welcome your feedback!

• Questions or ideas? Contact us at [e-mail]
• Issues or bugs? Report them on GitHub

We’re excited to support the forecasting community and make the API more useful for your needs.