{ "openapi": "3.0.1", "info": { "title": "Reddit Scraper: Posts, Comments, Subreddits, Users & Search", "description": "Scrape Reddit posts, full comment threads, subreddits, user profiles and search results. Filter by keyword, date, score, flair and subreddit. Get title, text, author, upvotes, comments and sentiment. Monitor new posts and go past the 1,000-post limit. Posts $2/1K, comments $0.60/1K.", "version": "1.0", "x-build-id": "enZSEelODObexnYeG" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/dltik~reddit-scraper-api/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-dltik-reddit-scraper-api", "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/dltik~reddit-scraper-api/runs": { "post": { "operationId": "runs-sync-dltik-reddit-scraper-api", "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/dltik~reddit-scraper-api/run-sync": { "post": { "operationId": "run-sync-dltik-reddit-scraper-api", "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": { "startUrls": { "title": "Reddit URLs (any type)", "type": "array", "description": "Universal input. Paste any Reddit URLs - subreddits, posts, user profiles, or search pages. Each URL is routed to the right mode automatically. Also accepts bare forms like 'r/python', 'u/spez', a post id, or a redd.it short link.", "items": { "type": "string" } }, "subredditUrls": { "title": "Subreddits", "type": "array", "description": "Subreddit names or URLs to scrape posts from (e.g. 'programming', 'r/python', or a full community URL). Use with Sort and Time filter below.", "items": { "type": "string" } }, "searchQuery": { "title": "Search query", "type": "string", "description": "Keyword or topic to search across all of Reddit (or one subreddit via 'Within subreddit'). Supports quoted \"exact phrases\" and author:/subreddit: operators." }, "withinSubreddit": { "title": "Within subreddit", "type": "string", "description": "Scope the search query to a single subreddit (name or URL). Leave empty to search all of Reddit." }, "searchType": { "title": "Search type", "enum": [ "posts", "comments", "communities", "users" ], "type": "string", "description": "What the search query returns: posts, comments, communities, or users.", "default": "posts" }, "postUrls": { "title": "Post URLs", "type": "array", "description": "Direct post URLs (or ids / redd.it short links) to scrape with their full comment thread.", "items": { "type": "string" } }, "usernames": { "title": "Usernames", "type": "array", "description": "Reddit usernames or profile URLs to scrape (profile + karma breakdown + trophies). Enable 'Include user history' for their posts/comments.", "items": { "type": "string" } }, "sort": { "title": "Sort", "enum": [ "hot", "new", "top", "rising", "controversial", "relevance", "comments" ], "type": "string", "description": "Sort order for subreddit feeds and search. Feeds: hot/new/top/rising/controversial. Search: relevance/hot/top/new/comments.", "default": "hot" }, "timeFilter": { "title": "Time filter", "enum": [ "hour", "day", "week", "month", "year", "all" ], "type": "string", "description": "Time window for 'top'/'controversial' sorts and search.", "default": "all" }, "maxPosts": { "title": "Max posts / results", "minimum": 1, "type": "integer", "description": "Maximum posts (or search results) to scrape per source. Reddit live feeds cap around 1000 per listing; use Archive mode for deeper history.", "default": 50 }, "includeComments": { "title": "Include comments", "type": "boolean", "description": "Also scrape the comment thread of each post. Comments are billed separately and cheaply ($0.60 / 1,000).", "default": false }, "maxCommentsPerPost": { "title": "Max comments per post", "minimum": 0, "type": "integer", "description": "Cap comments scraped per post. Set 0 to skip comments. The full nested tree (including 'load more comments') is expanded up to this cap.", "default": 50 }, "commentSort": { "title": "Comment sort", "enum": [ "top", "best", "new", "old", "controversial", "qa" ], "type": "string", "description": "How to sort each post's comment tree.", "default": "top" }, "commentDepthLimit": { "title": "Comment depth limit", "type": "integer", "description": "Maximum nesting depth to fetch (0 = top-level only). Leave empty for full depth." }, "expandMoreComments": { "title": "Expand 'load more comments'", "type": "boolean", "description": "Recursively expand collapsed 'load more comments' and 'continue this thread' nodes so giant threads are not truncated.", "default": true }, "includeSubredditAnalytics": { "title": "Include subreddit analytics", "type": "boolean", "description": "Emit one metadata record per subreddit with subscribers, description, rules, and moderators. Billed at $1.50 / 1,000.", "default": false }, "includeUserHistory": { "title": "Include user history", "type": "boolean", "description": "For scraped usernames, also pull their post and comment history (billed as posts/comments). Enable 'Use archive' to go past Reddit's ~1000-item cap.", "default": false }, "maxUserHistory": { "title": "Max user history items", "minimum": 1, "type": "integer", "description": "Maximum posts and comments to pull per user history.", "default": 100 }, "postedAfter": { "title": "Posted after", "type": "string", "description": "Only keep posts created on or after this date (YYYY-MM-DD)." }, "postedBefore": { "title": "Posted before", "type": "string", "description": "Only keep posts created on or before this date (YYYY-MM-DD)." }, "includeNsfw": { "title": "Include NSFW", "type": "boolean", "description": "Include NSFW (18+) posts. Off by default.", "default": false }, "onlyWithFlair": { "title": "Only posts with flair", "type": "boolean", "description": "Keep only posts that have a link flair set.", "default": false }, "keywords": { "title": "Keyword filter", "type": "array", "description": "Keep only posts matching these keywords (see Match mode). Case-insensitive.", "items": { "type": "string" } }, "keywordMatchMode": { "title": "Keyword match mode", "enum": [ "any", "all", "titleOnly", "exactPhrase" ], "type": "string", "description": "How the keyword filter matches: any keyword, all keywords, title only, or exact phrase.", "default": "any" }, "negativeKeywords": { "title": "Negative keywords", "type": "array", "description": "Drop posts containing any of these keywords (title or body). Case-insensitive.", "items": { "type": "string" } }, "minScore": { "title": "Min score", "type": "integer", "description": "Keep only posts with at least this score (upvotes)." }, "minComments": { "title": "Min comments", "type": "integer", "description": "Keep only posts with at least this many comments." }, "minUpvoteRatio": { "title": "Min upvote ratio", "type": "number", "description": "Keep only posts with at least this upvote ratio (0 to 1)." }, "computeSentiment": { "title": "Sentiment analysis", "type": "boolean", "description": "Add a free built-in sentiment_score and sentiment_label (AFINN-165) to every post and comment. No extra charge.", "default": true }, "aiAnalysis": { "title": "AI enrichment", "type": "boolean", "description": "Add LLM sentiment, intent, emotion, entities, relevance and category to each item. Billed $0.0005 per analyzed item.", "default": false }, "customLabels": { "title": "AI custom labels", "type": "array", "description": "User-defined true/false labels evaluated by the AI on each item (requires AI enrichment). Billed $0.0001 per label per item.", "items": { "type": "string" } }, "downloadMedia": { "title": "Download media", "type": "boolean", "description": "Download images, galleries and Reddit video (audio-muxed) to the key-value store instead of returning expiring URLs. Billed $0.0015 per asset stored.", "default": false }, "maxMediaPerPost": { "title": "Max media per post", "minimum": 1, "type": "integer", "description": "Maximum media assets to download per post (galleries can have many).", "default": 10 }, "outputFormat": { "title": "Output format", "enum": [ "default", "jsonl-finetune", "rag-markdown" ], "type": "string", "description": "Record shape: default rich JSON, jsonl-finetune (LLM SFT message pairs), or rag-markdown (chunked markdown for vector DBs).", "default": "default" }, "monitorMode": { "title": "Monitoring mode (incremental)", "type": "boolean", "description": "Only emit items not seen in previous runs with the same Monitor key. True incremental scraping - never pay twice for the same post.", "default": false }, "monitorKey": { "title": "Monitor key", "type": "string", "description": "Namespace for incremental dedup state. Use one key per recurring job." }, "useArchive": { "title": "Use archive (deep history)", "type": "boolean", "description": "Use the free Arctic Shift archive to backfill history beyond Reddit's ~1000-item live cap (for user history and Archive mode). Best-effort, polite rate.", "default": false }, "archiveSince": { "title": "Archive since", "type": "string", "description": "Archive mode: earliest date to fetch (YYYY-MM-DD)." }, "archiveUntil": { "title": "Archive until", "type": "string", "description": "Archive mode: latest date to fetch (YYYY-MM-DD)." }, "maxTotalChargeUsd": { "title": "Max total charge (USD)", "type": "number", "description": "Hard cost ceiling enforced continuously in-code. The run stops billing once this is reached and finishes as PARTIAL. Leave empty for no in-code cap." }, "redditClientId": { "title": "Reddit client id (optional, BYO app)", "type": "string", "description": "Bring your own Reddit app for a private, higher rate budget. Register a free app at reddit.com/prefs/apps ('installed app' needs only the id; 'script' also needs the secret). Leave empty to use the built-in access." }, "redditClientSecret": { "title": "Reddit client secret (optional)", "type": "string", "description": "Secret for a 'script'-type Reddit app. Not needed for 'installed app' type." }, "tokensPerClient": { "title": "Tokens per client", "minimum": 1, "maximum": 8, "type": "integer", "description": "How many OAuth tokens to mint per client id (each has its own 100-req/10min budget). Higher = more throughput.", "default": 2 }, "proxyConfig": { "title": "Proxy (optional)", "type": "object", "description": "Optional Apify proxy for IP rotation. Not required - oauth.reddit.com works from datacenter IPs.", "default": { "useApifyProxy": false } } } }, "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 } } } } } } } } } }