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

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

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```bash theme={null}
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](https://www.metaculus.com)
2. Generate an API token from your [account settings](https://www.metaculus.com/accounts/settings/account/#api-access)
3. Include the token in your requests using the `Authorization` header
4. Start making API requests!

<Warning>
  All API requests require valid authentication credentials. Unauthenticated requests will be rejected.
</Warning>

## Quick Example

Here's a simple example to retrieve recent posts:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://www.metaculus.com/api/posts/?limit=5" \
    -H "Authorization: Token YOUR_API_TOKEN"
  ```

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

  headers = {
      'Authorization': 'Token YOUR_API_TOKEN'
  }

  response = requests.get(
      'https://www.metaculus.com/api/posts/',
      headers=headers,
      params={'limit': 5}
  )

  posts = response.json()
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://www.metaculus.com/api/posts/?limit=5',
    {
      headers: {
        'Authorization': 'Token YOUR_API_TOKEN'
      }
    }
  );

  const posts = await response.json();
  ```
</CodeGroup>

## Support and Feedback

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

* **Questions or ideas?** Contact us at [api-requests@metaculus.com](mailto:api-requests@metaculus.com)
* **Issues or bugs?** Report them on [GitHub](https://github.com/Metaculus/metaculus/issues)

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