{ "openapi": "3.0.1", "info": { "title": "Substack Scraper: Newsletters, Posts, Subscribers, Leaderboards", "description": "Public Substack data with no login. Posts with likes, comments, restacks and free full text as Markdown. Newsletter profiles with subscriber counts, prices and socials. Find newsletters by keyword or category leaderboard. Only-new alerts. Failed inputs are free.", "version": "0.1", "x-build-id": "XJxoZB4AUvZAgBdkc" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/dottti~substack-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-dottti-substack-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/dottti~substack-scraper/runs": { "post": { "operationId": "runs-sync-dottti-substack-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/dottti~substack-scraper/run-sync": { "post": { "operationId": "run-sync-dottti-substack-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": { "mode": { "title": "What to get", "enum": [ "posts", "profiles", "discover" ], "type": "string", "description": "posts = posts from the newsletters you list. profiles = one profile row per newsletter (subscriber count, prices, ranking, socials). discover = find newsletters by keyword or category leaderboard.", "default": "posts" }, "newsletters": { "title": "Newsletters", "type": "array", "description": "For posts and profiles. Any of: a Substack name (lenny), a substack.com address (lenny.substack.com), a custom domain (https://www.lennysnewsletter.com) or a writer's @handle (@noahpinion).", "items": { "type": "string" } }, "postUrls": { "title": "Single post links", "type": "array", "description": "For posts mode. Links to single posts, such as https://www.astralcodexten.com/p/open-thread-458. Each link returns one post row.", "items": { "type": "string" } }, "maxPostsPerNewsletter": { "title": "Max posts per newsletter", "minimum": 0, "maximum": 10000, "type": "integer", "description": "Newest posts to fetch per newsletter. The archive goes back to the first post, so you can set a large number for a full archive.", "default": 20 }, "includeFullText": { "title": "Include full text of free posts", "type": "boolean", "description": "Adds the full article as Markdown (textMarkdown) for free posts. Paid posts are never unlocked: they get textStatus \"paywalled\" and the short public preview only. Turn off for faster metadata-only runs.", "default": true }, "audience": { "title": "Post audience", "enum": [ "all", "free", "paid" ], "type": "string", "description": "Keep all posts, only free posts or only paid (subscriber-only) posts.", "default": "all" }, "postedAfter": { "title": "Only posts after", "type": "string", "description": "Optional. A date (2026-10-01) or a relative time (24 hours, 7 days, 2 weeks, 3 months). Older posts are skipped and paging stops once a whole page is older." }, "includeNewsletterProfile": { "title": "Add a profile row per newsletter (posts mode)", "type": "boolean", "description": "In posts mode, also adds one profile row per newsletter, the same row that profiles mode returns.", "default": false }, "includeAuthorSocials": { "title": "Include author socials and ranking", "type": "boolean", "description": "For profile rows. Reads the writer's public Substack profile for social links (X, YouTube, LinkedIn, website), follower count and leaderboard rank. One extra request per newsletter.", "default": true }, "searchKeywords": { "title": "Search keywords", "type": "array", "description": "For discover mode. Topics such as climate, AI agents or personal finance. Returns writers' newsletters that match, with subscriber counts where Substack shows them.", "items": { "type": "string" } }, "categories": { "title": "Leaderboard categories", "type": "array", "description": "For discover mode. Substack categories by name or slug, such as technology, business, finance, culture, climate, crypto, health, sports. A wrong name returns a free status row that lists every valid one.", "items": { "type": "string" } }, "leaderboard": { "title": "Leaderboard", "enum": [ "bestsellers", "rising", "both" ], "type": "string", "description": "Which category leaderboard to read: Top Bestsellers (ranked by paid subscribers) or Rising.", "default": "bestsellers" }, "maxPublicationsPerSource": { "title": "Max newsletters per keyword or category", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Cap per keyword and per category leaderboard.", "default": 25 }, "onlyNew": { "title": "Only new items (alert mode)", "type": "boolean", "description": "Remembers what each newsletter, keyword and leaderboard returned last time and delivers only new posts or newly listed newsletters on the next run. Schedule the actor to get alerts. The first run delivers everything and saves the baseline. You pay only for new rows.", "default": false }, "stateName": { "title": "Alert state name", "type": "string", "description": "Keeps separate memories for different alert setups. Use a different name per schedule.", "default": "default" }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Optional. Leave empty: the actor starts with no proxy and moves to Apify datacenter, then residential proxy only if Substack starts refusing requests." }, "autoProxyFallback": { "title": "Automatic proxy fallback", "type": "boolean", "description": "When no proxy is set, climb from no proxy to datacenter to residential if Substack rate-limits the run.", "default": true }, "allowResidentialFallback": { "title": "Allow residential proxy in fallback", "type": "boolean", "description": "Residential proxy is the last step of the fallback. Turn off to stay on datacenter.", "default": true }, "maxConcurrency": { "title": "Parallel inputs", "minimum": 1, "maximum": 6, "type": "integer", "description": "How many newsletters, keywords or leaderboards run at the same time. Requests to substack.com itself are paced to avoid rate limits either way.", "default": 3 }, "maxRetries": { "title": "Retries per request", "minimum": 1, "maximum": 8, "type": "integer", "description": "Retries after a rate limit, server error or network error, with growing waits.", "default": 4 } } }, "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 } } } } } } } } } }