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.
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."
}
- 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:
- Create a Metaculus account at metaculus.com
- Generate an API token from your account settings
- Include the token in your requests using the
Authorization header
- 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 "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!
We’re excited to support the forecasting community and make the API more useful for your needs. 