{
  "openapi": "3.0.1",
  "info": {
    "title": "Reddit Scraper & Search API: Posts, Users, Subreddits",
    "description": "Search Reddit and scrape posts, subreddits and users from searches, subreddits or URLs. Filter by date, keywords, score and flair, get only new posts on schedules, and add comments, author activity and subreddit info.",
    "version": "0.1",
    "x-build-id": "k1o3U3TswKkSQlJZQ"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/parseforge~reddit-posts-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-parseforge-reddit-posts-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/acts/parseforge~reddit-posts-scraper/runs": {
      "post": {
        "operationId": "runs-sync-parseforge-reddit-posts-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor and returns information about the initiated run in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/runsResponseSchema"
                }
              }
            }
          }
        }
      }
    },
    "/acts/parseforge~reddit-posts-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-parseforge-reddit-posts-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "inputSchema": {
        "type": "object",
        "properties": {
          "maxItems": {
            "title": "Maximum Posts",
            "minimum": 1,
            "maximum": 1000000,
            "type": "integer",
            "description": "How many posts to collect per run."
          },
          "startUrls": {
            "title": "Reddit post or subreddit URLs",
            "type": "array",
            "description": "Direct Reddit URLs to scrape. Supports subreddit URLs and search URLs.\n\nExamples:\n- https://www.reddit.com/r/programming/\n- https://www.reddit.com/r/javascript/top/\n- https://www.reddit.com/search?q=machine+learning",
            "items": {
              "type": "object",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "title": "URL of a web page",
                  "format": "uri"
                }
              }
            }
          },
          "directUrls": {
            "title": "Direct post URLs (deprecated, use \"Reddit post or subreddit URLs\")",
            "type": "array",
            "description": "Deprecated alias for `startUrls`, kept for inputs and schedules saved before this version. New runs should use `startUrls` instead.",
            "items": {
              "type": "object",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "title": "URL of a web page",
                  "format": "uri"
                }
              }
            }
          },
          "subreddits": {
            "title": "📱 Subreddits",
            "type": "array",
            "description": "List of subreddits to scrape posts from (without r/ prefix).\n\nExamples: programming, javascript, datascience",
            "items": {
              "type": "string"
            }
          },
          "searchQueries": {
            "title": "Search terms for posts",
            "type": "array",
            "description": "Search terms to find posts across Reddit. Each query will search all of Reddit unless you specify a subreddit in the query.\n\nExamples:\n- machine learning\n- best programming language 2025\n- subreddit:programming typescript",
            "items": {
              "type": "string"
            }
          },
          "searchInSubreddit": {
            "title": "Subreddit name",
            "type": "string",
            "description": "Limit search queries to a specific subreddit (optional). Leave empty to search all of Reddit."
          },
          "searchTypes": {
            "title": "What to search for",
            "type": "array",
            "description": "What each search term looks for. Leave empty for posts. Communities and users come back as their own rows with a `type` field.",
            "items": {
              "type": "string",
              "enum": [
                "posts",
                "communities",
                "users"
              ],
              "enumTitles": [
                "Posts",
                "Communities (subreddits)",
                "Users"
              ]
            }
          },
          "sort": {
            "title": "🔄 Sort By",
            "enum": [
              "hot",
              "new",
              "top",
              "rising",
              "controversial",
              "relevance"
            ],
            "type": "string",
            "description": "How to sort the posts:\n\n- hot: Currently popular posts\n- new: Most recent posts\n- top: Highest scored posts (use with Time Filter)\n- rising: Posts gaining momentum\n- controversial: Most debated posts\n- relevance: Best match (search only)",
            "default": "hot"
          },
          "time": {
            "title": "⏰ Time Filter",
            "enum": [
              "hour",
              "day",
              "week",
              "month",
              "year",
              "all"
            ],
            "type": "string",
            "description": "Time range for 'top', 'controversial', and search results:\n\n- hour: Past hour\n- day: Past 24 hours\n- week: Past 7 days\n- month: Past 30 days\n- year: Past 365 days\n- all: All time",
            "default": "day"
          },
          "includeNSFW": {
            "title": "🔞 Include NSFW Content",
            "type": "boolean",
            "description": "Include posts marked as NSFW (Not Safe For Work / 18+)",
            "default": true
          },
          "includeSpoilers": {
            "title": "⚠️ Include Spoilers",
            "type": "boolean",
            "description": "Include posts marked as spoilers",
            "default": true
          },
          "includeStickied": {
            "title": "📌 Include Stickied Posts",
            "type": "boolean",
            "description": "Include moderator-pinned posts at the top of subreddits",
            "default": true
          },
          "minScore": {
            "title": "⬆️ Minimum Score",
            "minimum": 0,
            "type": "integer",
            "description": "Only include posts with at least this many upvotes. Leave empty for no minimum."
          },
          "maxScore": {
            "title": "Maximum Score",
            "minimum": 0,
            "type": "integer",
            "description": "Only include posts with at most this many upvotes. Leave empty for no maximum."
          },
          "minComments": {
            "title": "💬 Minimum Comments",
            "minimum": 0,
            "type": "integer",
            "description": "Only include posts with at least this many comments. Leave empty for no minimum."
          },
          "maxComments": {
            "title": "Maximum Comments",
            "minimum": 0,
            "type": "integer",
            "description": "Only include posts with at most this many comments. Leave empty for no maximum."
          },
          "flairFilter": {
            "title": "🏷️ Flair Filter",
            "type": "string",
            "description": "Only include posts with one of these flairs. Separate several with commas. Not case-sensitive.\n\nExample: Discussion, Question, Tutorial"
          },
          "domainFilter": {
            "title": "🌐 Domain Filter",
            "type": "string",
            "description": "Only include posts from URLs containing this domain.\n\nExamples: youtube.com, github.com, imgur.com"
          },
          "authorFilter": {
            "title": "👤 Author Filter",
            "type": "string",
            "description": "Only include posts from this specific author (username without u/)."
          },
          "excludeFlairs": {
            "title": "🏷️ Exclude flairs",
            "type": "array",
            "description": "Drop posts with any of these flairs. Not case-sensitive.",
            "items": {
              "type": "string"
            }
          },
          "includeKeywords": {
            "title": "🔑 Must contain one of these words",
            "type": "array",
            "description": "Keep only posts whose title or body contains at least one of these words or phrases. Not case-sensitive.",
            "items": {
              "type": "string"
            }
          },
          "excludeKeywords": {
            "title": "🚫 Must not contain these words",
            "type": "array",
            "description": "Drop posts whose title or body contains any of these words or phrases. Not case-sensitive.",
            "items": {
              "type": "string"
            }
          },
          "postedAfter": {
            "title": "📅 Posted after",
            "type": "string",
            "description": "Keep only posts created after this date, or within a relative window such as 7 days. On feeds sorted by new, reading stops once posts get older than this."
          },
          "postedBefore": {
            "title": "📅 Posted before",
            "type": "string",
            "description": "Keep only posts created before this date, or older than a relative window such as 1 day."
          },
          "contentTypes": {
            "title": "🖼️ Content types",
            "type": "array",
            "description": "Keep only these kinds of posts. Leave empty for all.",
            "items": {
              "type": "string",
              "enum": [
                "text",
                "link",
                "image",
                "video",
                "gallery"
              ],
              "enumTitles": [
                "Text posts",
                "Links",
                "Images",
                "Videos",
                "Galleries"
              ]
            }
          },
          "excludeDomains": {
            "title": "🌐 Exclude domains",
            "type": "array",
            "description": "Drop posts linking to any of these domains, for example youtube.com.",
            "items": {
              "type": "string"
            }
          },
          "excludeAuthors": {
            "title": "👤 Exclude authors",
            "type": "array",
            "description": "Drop posts from these usernames, for example AutoModerator.",
            "items": {
              "type": "string"
            }
          },
          "minUpvotePercent": {
            "title": "👍 Minimum upvote percentage",
            "minimum": 0,
            "maximum": 100,
            "type": "integer",
            "description": "Keep only posts with at least this share of upvotes (0-100). Leave empty for no minimum."
          },
          "onlyNewSinceLastRun": {
            "title": "🆕 Only posts not collected in earlier runs",
            "type": "boolean",
            "description": "For schedules: skip posts this same input already collected in an earlier run, so you only get and pay for new ones. The list is kept in a key-value store named reddit-posts-scraper-state in your account.",
            "default": false
          },
          "stateKey": {
            "title": "🆕 State name (optional)",
            "type": "string",
            "description": "Share or separate the 'already collected' list between inputs. Leave empty to derive it from the sources."
          },
          "maxPages": {
            "title": "Maximum Pages Per Source",
            "minimum": 1,
            "maximum": 100,
            "type": "integer",
            "description": "Maximum number of pages to scrape per subreddit/query. Each page contains up to 100 posts.",
            "default": 10
          },
          "postsPerSource": {
            "title": "📝 Posts Per Source",
            "minimum": 1,
            "maximum": 1000,
            "type": "integer",
            "description": "Maximum posts to scrape from each subreddit or search query.",
            "default": 100
          },
          "includeAuthorProfile": {
            "title": "👤 Include author profile",
            "type": "boolean",
            "description": "Fetch each post author's public profile (karma, account age, verified status) and attach it under the `authorProfile` field. Charged once per author. Off by default.",
            "default": false
          },
          "includeComments": {
            "title": "💬 Include comments",
            "type": "boolean",
            "description": "Fetch the top comments for each post and attach them under the `comments` field. Charged with the comment event (see Pricing). Off by default.",
            "default": false
          },
          "commentLimit": {
            "title": "💬 Comments per post",
            "minimum": 1,
            "maximum": 200,
            "type": "integer",
            "description": "How many top comments to fetch per post when 'Include comments' is on.",
            "default": 20
          },
          "commentDepth": {
            "title": "💬 Reply depth",
            "minimum": 1,
            "maximum": 10,
            "type": "integer",
            "description": "1 returns top-level comments only. Higher values include replies down to that depth, each with `depth` and `parentId`.",
            "default": 1
          },
          "includeSubredditInfo": {
            "title": "🏘️ Include subreddit info",
            "type": "boolean",
            "description": "Attach the subreddit's subscribers, active users, creation date and description under `subredditInfo`. Charged once per subreddit.",
            "default": false
          },
          "includeUserHistory": {
            "title": "🕘 Include author's recent activity",
            "type": "boolean",
            "description": "Attach the author's latest posts and comments under `authorHistory`. Charged once per author.",
            "default": false
          },
          "userHistoryLimit": {
            "title": "🕘 Items of recent activity",
            "minimum": 1,
            "maximum": 100,
            "type": "integer",
            "description": "How many recent posts and comments to attach per author.",
            "default": 10
          },
          "includeCrossposts": {
            "title": "🔁 Include crossposts",
            "type": "boolean",
            "description": "Attach other submissions of the same link (crossposts and reposts) under `crossposts`. Charged per post checked. Off by default.",
            "default": false
          },
          "downloadMedia": {
            "title": "🖼️ Download post images",
            "type": "boolean",
            "description": "Download each post's image (and thumbnail) and host it on Apify storage, attaching the hosted URL under the `media` field. Images only — videos are skipped. Off by default.",
            "default": false
          },
          "mcpConnector": {
            "title": "🔗 MCP Connector",
            "type": "string",
            "description": "Pick a connector (Notion, Linear, Airtable, Jira, Monday, etc.) or click '+' to create a new one via OAuth. See the README for the full list of 16 verified-working MCP services with use case examples."
          },
          "mcpMode": {
            "title": "🔗 Mode",
            "enum": [
              "perPost",
              "summary"
            ],
            "type": "string",
            "description": "Per-post: one Notion sub-page / GitHub issue / Linear ticket per scraped Reddit post (default). Summary: a single message at the end with top post + stats.",
            "default": "perPost"
          },
          "mcpTarget": {
            "title": "🔗 Target page / database / repo",
            "type": "string",
            "description": "For services that need a destination: paste the URL or ID. Notion example: https://www.notion.so/Reddit-abc123def. Slack/Discord don't need this. For Notion, connect the target page to your Apify integration via Notion's Connections menu before running."
          },
          "mcpMessage": {
            "title": "🔗 Custom template (advanced)",
            "type": "string",
            "description": "Leave empty for a pretty pre-formatted default. Or write your own Markdown — Notion renders headings (#), lists (-), quotes (>), bold (**), links ([text](url)), dividers (---).\n\nPer-post placeholders: {{post.title}}, {{post.url}}, {{post.author}}, {{post.score}}, {{post.subreddit}}, {{post.permalink}}, {{post.numComments}}, {{post.selfText}}, {{post.createdAt}}, {{post.domain}}.\n\nSummary placeholders: {{totalPosts}}, {{durationSec}}, {{topPost.title}}, {{topPost.url}}, {{topPost.score}}, {{topPost.author}}, {{topPost.subreddit}}, {{datasetUrl}}."
          },
          "mcpTool": {
            "title": "🔗 Tool name override (advanced)",
            "type": "string",
            "description": "Override the auto-detected MCP tool. By default the actor picks the first write-style tool on the connector (e.g. send_message for Slack, notion-create-pages for Notion, create_issue for Linear/GitHub). Leave empty for auto-detect."
          },
          "mcpArguments": {
            "title": "🔗 Arguments JSON override (advanced)",
            "type": "object",
            "description": "Override the full argument shape (e.g. Notion's rich_text blocks). If empty, arguments are auto-built from the message + the tool's inputSchema. Leave empty for normal use."
          },
          "mcpProxyUrlOverride": {
            "title": "🛠 MCP proxy URL override (dev/diagnostic)",
            "type": "string",
            "description": "Diagnostic only. Bypasses Apify's MCP proxy and talks directly to an MCP server URL — useful for debugging Apify proxy issues. Example: https://mcp.airtable.com/mcp. Leave empty for normal use."
          },
          "mcpTokenOverride": {
            "title": "🛠 MCP bearer token override (dev/diagnostic)",
            "type": "string",
            "description": "Diagnostic only. Used with the URL override above — paste the service's API key or PAT to authenticate directly. Example: for Airtable, get a PAT at airtable.com/create/tokens with scopes data.records:write + schema.bases:read. Leave empty for normal use."
          }
        }
      },
      "runsResponseSchema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "actId": {
                "type": "string"
              },
              "userId": {
                "type": "string"
              },
              "startedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "finishedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "status": {
                "type": "string",
                "example": "READY"
              },
              "meta": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string",
                    "example": "API"
                  },
                  "userAgent": {
                    "type": "string"
                  }
                }
              },
              "stats": {
                "type": "object",
                "properties": {
                  "inputBodyLen": {
                    "type": "integer",
                    "example": 2000
                  },
                  "rebootCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "restartCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "resurrectCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "computeUnits": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "options": {
                "type": "object",
                "properties": {
                  "build": {
                    "type": "string",
                    "example": "latest"
                  },
                  "timeoutSecs": {
                    "type": "integer",
                    "example": 300
                  },
                  "memoryMbytes": {
                    "type": "integer",
                    "example": 1024
                  },
                  "diskMbytes": {
                    "type": "integer",
                    "example": 2048
                  }
                }
              },
              "buildId": {
                "type": "string"
              },
              "defaultKeyValueStoreId": {
                "type": "string"
              },
              "defaultDatasetId": {
                "type": "string"
              },
              "defaultRequestQueueId": {
                "type": "string"
              },
              "buildNumber": {
                "type": "string",
                "example": "1.0.0"
              },
              "containerUrl": {
                "type": "string"
              },
              "usage": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "integer",
                    "example": 1
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "usageTotalUsd": {
                "type": "number",
                "example": 0.00005
              },
              "usageUsd": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "number",
                    "example": 0.00005
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}