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

# Posts

> Retrieve and filter the Metaculus feed

## Overview

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

* **Individual Questions** - Single binary, multiple choice, numeric, date, or discrete questions
* **Groups of Questions** - Multiple related questions displayed together
* **Conditional Questions** - "If Yes" / "If No" scenario pairs
* **Notebooks** - Long-form content without forecasting components

The Posts endpoint is your main entry point for discovering and filtering forecasting questions.

***

## List Posts

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://www.metaculus.com/api/posts/?statuses=open&limit=20" \
    -H "Authorization: Token YOUR_TOKEN"
  ```

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

  response = requests.get(
      "https://www.metaculus.com/api/posts/",
      headers={"Authorization": "Token YOUR_TOKEN"},
      params={
          "statuses": "open",
          "limit": 20
      }
  )
  print(response.json())
  ```
</CodeGroup>

`GET /api/posts/`

Retrieve a paginated feed of posts with extensive filtering and sorting options.

### Query Parameters

#### Status & Lifecycle Filters

<ParamField query="statuses" type="array">
  Filter by post status. Multiple values allowed: `open`, `closed`, `resolved`, `upcoming`

  Example: `?statuses=open&statuses=closed`
</ParamField>

<ParamField query="for_main_feed" type="boolean">
  Filter posts suitable for the main feed (excludes drafts, rejected, etc.)
</ParamField>

#### Project & Category Filters

<ParamField query="tournaments" type="array">
  Filter by tournament slug. Multiple values allowed.

  Example: `?tournaments=metaculus-cup&tournaments=aibq3`
</ParamField>

<ParamField query="categories" type="array">
  Filter by category slug. Multiple values allowed.

  Example: `?categories=nuclear&categories=health-pandemics`
</ParamField>

<ParamField query="topic" type="string">
  Filter by a single topic slug
</ParamField>

<ParamField query="community" type="string">
  Filter by community slug
</ParamField>

#### Forecaster Filters

<ParamField query="forecaster_id" type="integer">
  Show only posts where this user has submitted a forecast
</ParamField>

<ParamField query="not_forecaster_id" type="integer">
  Show only posts where this user has NOT submitted a forecast
</ParamField>

#### Question Type Filters

<ParamField query="forecast_type" type="array">
  Filter by question type: `binary`, `multiple_choice`, `numeric`, `discrete`, `date`, `conditional`, `group_of_questions`, `notebook`

  Example: `?forecast_type=binary&forecast_type=numeric`
</ParamField>

#### Timestamp Filters

<ParamField query="open_time__gt" type="string (datetime)">
  Posts opened after this timestamp. Also supports: `__gte`, `__lt`, `__lte`

  Example: `?open_time__gt=2024-01-01`
</ParamField>

<ParamField query="published_at__gt" type="string (datetime)">
  Posts published after this timestamp. Also supports: `__gte`, `__lt`, `__lte`
</ParamField>

<ParamField query="scheduled_resolve_time__gt" type="string (datetime)">
  Posts scheduled to resolve after this timestamp. Also supports: `__gte`, `__lt`, `__lte`
</ParamField>

#### Pagination

<ParamField query="limit" type="integer" default="20">
  Number of posts to return per page
</ParamField>

<ParamField query="offset" type="integer" default="0">
  Number of posts to skip
</ParamField>

#### Data Inclusion

<ParamField query="with_cp" type="boolean" default="false">
  Include community predictions. For groups, only returns CP for top 3 subquestions.
</ParamField>

<ParamField query="include_cp_history" type="boolean" default="false">
  Include full aggregation history. Significantly increases response size.
</ParamField>

<ParamField query="include_descriptions" type="boolean" default="false">
  Include description, fine\_print, and resolution\_criteria fields
</ParamField>

#### Sorting

<ParamField query="order_by" type="string">
  Sort posts by field. Prefix with `-` for descending order.

  Options:

  * `published_at` - Publication date
  * `open_time` - Opening date
  * `scheduled_close_time` - Close date
  * `scheduled_resolve_time` - Resolution date
  * `vote_score` - Community votes
  * `comment_count` - Number of comments
  * `forecasts_count` - Number of forecasts
  * `hotness` - Trending score (decay function based on engagement)
  * `weekly_movement` - Community prediction change
  * `divergence` - Spread of user predictions
  * `score` - User performance (requires `forecaster_id`)

  Example: `?order_by=-hotness`
</ParamField>

### Response

<ResponseField name="next" type="string">
  URL for the next page of results, or null if no more pages
</ResponseField>

<ResponseField name="previous" type="string">
  URL for the previous page of results, or null if on first page
</ResponseField>

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

### Post Object Structure

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

<ResponseField name="title" type="string">
  Post title
</ResponseField>

<ResponseField name="short_title" type="string">
  Shortened title for URLs
</ResponseField>

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

<ResponseField name="author_id" type="integer">
  User ID of the post author
</ResponseField>

<ResponseField name="author_username" type="string">
  Username of the post author
</ResponseField>

<ResponseField name="created_at" type="string (datetime)">
  When the post was created
</ResponseField>

<ResponseField name="published_at" type="string (datetime)">
  When the post was published
</ResponseField>

<ResponseField name="open_time" type="string (datetime)">
  When forecasting opened
</ResponseField>

<ResponseField name="scheduled_close_time" type="string (datetime)">
  When forecasting is scheduled to close
</ResponseField>

<ResponseField name="scheduled_resolve_time" type="string (datetime)">
  When the question is scheduled to resolve
</ResponseField>

<ResponseField name="status" type="string">
  Current status: `open`, `closed`, `resolved`, `upcoming`, `draft`, `pending`, `rejected`
</ResponseField>

<ResponseField name="curation_status" type="string">
  Curation state: `draft`, `pending`, `rejected`, `approved`
</ResponseField>

<ResponseField name="comment_count" type="integer">
  Number of comments on this post
</ResponseField>

<ResponseField name="nr_forecasters" type="integer">
  Number of unique forecasters
</ResponseField>

<ResponseField name="forecasts_count" type="integer">
  Total number of forecasts submitted
</ResponseField>

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

<ResponseField name="vote" type="object">
  Voting information

  <ResponseField name="score" type="integer">
    Total vote score
  </ResponseField>

  <ResponseField name="user_vote" type="integer">
    Current user's vote: `1` (upvote), `-1` (downvote), or `null`
  </ResponseField>
</ResponseField>

<ResponseField name="projects" type="object">
  Associated projects, categories, and tournaments

  <ResponseField name="site_main" type="array">
    Main site projects
  </ResponseField>

  <ResponseField name="tournament" type="array">
    Associated tournaments
  </ResponseField>

  <ResponseField name="category" type="array">
    Associated categories
  </ResponseField>

  <ResponseField name="tag" type="array">
    Associated tags
  </ResponseField>

  <ResponseField name="default_project" type="object">
    The primary project for this post
  </ResponseField>
</ResponseField>

<ResponseField name="question" type="object">
  Question data (if post contains a single question). See Questions endpoint for full schema.
</ResponseField>

<ResponseField name="conditional" type="object">
  Conditional question data (if post contains conditional questions)

  <ResponseField name="condition" type="object">
    The parent condition question (binary)
  </ResponseField>

  <ResponseField name="condition_child" type="object">
    The conditional child question
  </ResponseField>

  <ResponseField name="question_yes" type="object">
    Question for "If Yes" scenario
  </ResponseField>

  <ResponseField name="question_no" type="object">
    Question for "If No" scenario
  </ResponseField>
</ResponseField>

<ResponseField name="group_of_questions" type="object">
  Group of questions data (if post contains multiple questions)

  <ResponseField name="id" type="integer">
    Group identifier
  </ResponseField>

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

  <ResponseField name="resolution_criteria" type="string">
    How questions in this group will be resolved
  </ResponseField>

  <ResponseField name="group_variable" type="string">
    The variable that changes across questions (e.g., "Date", "Country")
  </ResponseField>

  <ResponseField name="graph_type" type="string">
    Visualization type: `multiple_choice_graph` or `fan_graph`
  </ResponseField>

  <ResponseField name="questions" type="array">
    Array of question objects in this group
  </ResponseField>
</ResponseField>

<ResponseField name="notebook" type="object">
  Notebook content (if post is a notebook)

  <ResponseField name="markdown" type="string">
    The notebook content in markdown
  </ResponseField>

  <ResponseField name="image_url" type="string">
    Featured image URL
  </ResponseField>
</ResponseField>

***

## Get Post Details

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

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

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

`GET /api/posts/{postId}/`

Retrieve detailed information about a specific post, including all associated questions and community predictions.

### Path Parameters

<ParamField path="postId" type="integer" required>
  The unique identifier of the post
</ParamField>

### Response

Returns a single post object with the same structure as the list endpoint, but with more complete data including:

* Full community prediction history for all questions
* Complete descriptions and resolution criteria
* All subquestions in groups (not limited to top 3)

***

## Example Response

```json theme={null}
{
  "next": "https://www.metaculus.com/api/posts/?limit=1&offset=1",
  "previous": null,
  "results": [
    {
      "id": 3530,
      "title": "How many people will die as a result of COVID-19 before 2021?",
      "short_title": "COVID-19 Related Deaths before 2021",
      "slug": "covid-19-related-deaths-before-2021",
      "author_id": 101465,
      "author_username": "Jgalt",
      "created_at": "2020-01-25T04:09:23.208127Z",
      "published_at": "2020-01-27T00:00:00Z",
      "open_time": "2020-01-27T00:00:00Z",
      "scheduled_close_time": "2020-11-01T00:00:00Z",
      "scheduled_resolve_time": "2022-05-06T16:00:00Z",
      "status": "resolved",
      "curation_status": "approved",
      "comment_count": 270,
      "nr_forecasters": 546,
      "forecasts_count": 2760,
      "user_permission": "forecaster",
      "vote": {
        "score": 172,
        "user_vote": null
      },
      "question": {
        "id": 3530,
        "title": "How many people will die as a result of COVID-19 before 2021?",
        "type": "numeric",
        "status": "resolved",
        "resolution": "77289125.94957079",
        "scaling": {
          "range_min": 200.0,
          "range_max": 100000000.0,
          "zero_point": 0.0,
          "open_upper_bound": true,
          "open_lower_bound": true
        }
      },
      "projects": {
        "category": [
          {
            "id": 3685,
            "name": "Health & Pandemics",
            "slug": "health-pandemics"
          }
        ],
        "default_project": {
          "id": 144,
          "name": "Metaculus Community",
          "type": "site_main"
        }
      }
    }
  ]
}
```