{ "openapi": "3.0.1", "info": { "title": "Substack Scraper — Posts, Engagement & Paywall API", "description": "Find newsletters by keyword, then scrape their full archives with engagement flattened into numbers: reactions, comments, restacks, word count and free-vs-paid status. Discovery walks the category tree, because Substack's own search returns empty for anonymous callers.", "version": "0.7", "x-build-id": "vaxClkrOuAVIbvSPm" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/cleanrows~substack-posts-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-cleanrows-substack-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/cleanrows~substack-posts-scraper/runs": { "post": { "operationId": "runs-sync-cleanrows-substack-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/cleanrows~substack-posts-scraper/run-sync": { "post": { "operationId": "run-sync-cleanrows-substack-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": { "publications": { "title": "Publications", "type": "array", "description": "Substack slugs, subdomains or custom domains. `noahpinion`, `bariweiss.substack.com` and `www.thefp.com` all work. Optional if you use Discover keywords instead.", "default": [], "items": { "type": "string" } }, "discoverKeywords": { "title": "Discover by keyword", "type": "array", "description": "Find newsletters covering a subject instead of naming them. Matches against publication name, tagline, author bio and handle across Substack's category tree. Results feed the same post pipeline unless Discover only is set. Matched as whole words against a publication name, bio and subdomain, so a short keyword like AI does not match said, again or email.", "default": [], "items": { "type": "string" } }, "discoverCategories": { "title": "Limit discovery to categories", "type": "array", "description": "Category slugs such as technology, business, finance, us-politics, health-politics, food, sports, music, news. Empty searches all 32, which is slower but finds newsletters filed somewhere unexpected.", "default": [], "items": { "type": "string" } }, "maxPagesPerCategory": { "title": "Pages scanned per category", "minimum": 1, "maximum": 40, "type": "integer", "description": "25 publications per page, ranked by popularity, so the early pages hold the newsletters people have heard of. Raise it to reach further down the tail.", "default": 4 }, "maxPublications": { "title": "Max publications discovered", "minimum": 1, "type": "integer", "description": "Stop once this many distinct publications match.", "default": 25 }, "discoverOnly": { "title": "Discover only, do not fetch posts", "type": "boolean", "description": "Return the matching publications themselves - name, url, tagline, author, category and the keyword that matched - instead of their posts. Answers which newsletters cover a subject without paying per post to find out.", "default": false }, "sort": { "title": "Sort", "enum": [ "new", "top" ], "type": "string", "description": "Order requested from Substack.", "default": "new" }, "audience": { "title": "Free or paid", "enum": [ "all", "free", "paid" ], "type": "string", "description": "Filter by whether the post sits behind the paywall.", "default": "all" }, "searchQuery": { "title": "Search", "type": "string", "description": "Keep only posts whose title, subtitle or description contains this text.", "default": "" }, "postedWithinDays": { "title": "Posted within (days)", "minimum": 0, "type": "integer", "description": "Keep only posts published in the last N days. 0 disables the filter.", "default": 0 }, "maxItemsPerPublication": { "title": "Max posts per publication", "minimum": 0, "type": "integer", "description": "Stop after this many posts from each publication. 0 fetches the entire archive, which can run to thousands.", "default": 100 }, "maxItems": { "title": "Max posts", "minimum": 0, "type": "integer", "description": "Stop after this many posts across all publications. 0 means no limit.", "default": 0 } } }, "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 } } } } } } } } } }