{ "openapi": "3.0.1", "info": { "title": "Reddit Scraper - Posts, Comments, Users, Search & Subreddits", "description": "Scrape Reddit via the official API. Posts, full comment trees, user history, subreddit rules/mods, search, sentiment, media download and monitoring. No browser. From $0.60 per 1,000 comments, $2 per 1,000 posts.", "version": "1.0", "x-build-id": "ii8TULYuoRT4BvdIh" }, "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 } } }, "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 } } } } } } } } } }