# Substack Scraper — Posts, Authors & Newsletter Data (`sian.agency/substack-scraper`) Actor

Substack newsletter scraper for any publication. Extract posts: title, subtitle, author, date, reactions, comments, restacks, word count, cover image — plus full article HTML in detail mode. Search by handle, subdomain or custom domain. Clean JSON/CSV, no-code, no API key needed.

- **URL**: https://apify.com/sian.agency/substack-scraper.md
- **Developed by:** [SIÁN OÜ](https://apify.com/sian.agency) (community)
- **Categories:** News, Social media, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.60 / 1,000 post extracted (overview)s

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md).

If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).


# README

## Substack Scraper — Posts, Authors & Newsletter Data 🚀

[![SIÁN Agency Store](https://img.shields.io/badge/Store-SI%C3%81N%20Agency-1AE392)](https://apify.com/sian.agency?fpr=sian) [![Instagram AI Transcript](https://img.shields.io/badge/Store-Instagram%20AI%20Transcript-E4405F)](https://apify.com/sian.agency/instagram-ai-transcript-extractor?fpr=sian) [![TikTok AI Transcript](https://img.shields.io/badge/Store-TikTok%20AI%20Transcript-25F4EE)](https://apify.com/sian.agency/tiktok-ai-transcript-extractor?fpr=sian) [![Facebook AI Transcript](https://img.shields.io/badge/Store-Facebook%20AI%20Transcript-1877F2)](https://apify.com/sian.agency/facebook-ai-transcript-extractor?fpr=sian)

#### 🎉 Turn any Substack newsletter into a clean, structured dataset — metadata, engagement, authors, and full article text.
##### Built for content researchers, marketers, and analysts who need newsletter data at scale.

---

### 📋 Overview

**Point it at any Substack publication and get every post as clean structured data** — no account, no API key, no copy-pasting. Works with handles, `*.substack.com` subdomains, and custom domains alike.

**Why professionals choose this scraper:**
- ✅ **Complete post data**: title, subtitle, author(s), publish date, word count, cover image, and more — 30+ fields per post
- ⚡ **Two modes, one tool**: fast Overview for bulk archive metadata, or Detail for the full article HTML
- 🎯 **Engagement built in**: reactions, comments, restacks, and a combined engagement score on every row
- 💰 **Pay-per-result**: only pay for posts you actually extract — transparent and predictable
- 💎 **Any publication**: handle, subdomain, or custom domain — all supported automatically
- ✨ **Clean export**: JSON, CSV, or Excel straight from the Apify dataset

---

### ✨ Features

- 📰 **Publication Archive Scraping**: page through a newsletter's entire back catalog of posts
- 📄 **Full Article HTML**: pull the complete post body, ready for analysis or archiving
- ✍️ **Author Extraction**: every byline with name, handle, and avatar
- ❤️ **Engagement Metrics**: reactions (with emoji breakdown), comments, and restacks
- 🖼️ **Image Capture**: cover image plus every in-body image URL, deduplicated
- 🔓 **Audience Tags**: see which posts are free, paid, or founder-only at a glance
- 🔢 **Smart Limits**: cap posts per run and pages per publication for precise, predictable runs
- 🌐 **Custom Domains**: works seamlessly whether a writer uses `*.substack.com` or their own domain

---

### 🎬 Quick Start

Paste a publication handle, pick a mode, and run. Results land in your dataset within seconds.

```bash
curl -X POST https://api.apify.com/v2/acts/sian.agency~substack-scraper/runs?token=YOUR_TOKEN \
-H 'Content-Type: application/json' \
-d '{"scrapeMode": "overview", "publications": ["bigtechnology"], "maxResults": 50}'
````

***

### 🚀 Getting Started (3 Simple Steps)

#### Step 1: Add your publications

Enter one or more Substack publications — a handle (`bigtechnology`), a subdomain (`bigtechnology.substack.com`), or a custom domain (`www.bigtechnology.com`).

#### Step 2: Choose a mode

Pick **Overview** for fast archive metadata, or **Detail** for the complete article HTML.

#### Step 3: Run and export

Start the actor and download your results as JSON, CSV, or Excel.

**That's it! In under a minute, you'll have:**

- A structured table of posts with authors and dates
- Engagement metrics for every post
- (Detail mode) the full article text, ready to analyze

***

### 📥 Input Configuration

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| scrapeMode | string | No | `overview` (archive metadata) or `detail` (full article HTML) |
| publications | array | No | Publications to scrape — handle, subdomain, or custom domain |
| postUrls | array | No | Specific post URLs (`/p/<slug>`) to fetch in Detail mode |
| maxResults | integer | No | Max posts per run (FREE: 25, PAID: unlimited) |
| endpoint | string | No | `archive` (recommended) or `posts` |
| sort | string | No | `new` (newest first) or `top` (most popular) |
| maxPagesPerPublication | integer | No | Limit pages crawled per publication |
| useProxy | boolean | No | Optional residential routing for very high volume |

**Example — Overview:**

```json
{
  "scrapeMode": "overview",
  "publications": ["bigtechnology", "www.thefp.com"],
  "sort": "new",
  "maxResults": 100
}
```

**Example — Detail by URL:**

```json
{
  "scrapeMode": "detail",
  "postUrls": [
    "https://www.bigtechnology.com/p/greg-brockman-on-openais-plan-to"
  ]
}
```

***

### 📤 Output

Results are saved to the Apify dataset with **30+ fields** including:

| Field | Type | Description |
|-------|------|-------------|
| title | string | Post title |
| subtitle | string | Subtitle or social title |
| url | string | Canonical post URL |
| post\_date | string | ISO 8601 publish date |
| audience | string | everyone / only\_paid / founding |
| reaction\_count | number | Total reactions |
| comment\_count | number | Number of comments |
| restacks | number | Number of restacks |
| engagement\_total | number | Reactions + comments + restacks |
| wordcount | number | Article word count |
| bylines | array | Authors with name, handle, avatar |
| cover\_image | string | Cover image URL |
| body\_html | string | Full article HTML (Detail mode) |

**Example:**

```json
{
  "id": 202753370,
  "title": "Greg Brockman On OpenAI's Plan To Win: Compute Rules All",
  "url": "https://www.bigtechnology.com/p/greg-brockman-on-openais-plan-to",
  "publication_host": "bigtechnology.substack.com",
  "post_date": "2026-06-19T18:39:54.460Z",
  "audience": "everyone",
  "reaction_count": 27,
  "comment_count": 3,
  "restacks": 2,
  "engagement_total": 32,
  "wordcount": 1017,
  "bylines": [{ "name": "Marty Swant", "handle": "martyswant" }],
  "thumbnail": "https://substackcdn.com/image/...",
  "source": "overview"
}
```

***

### 💼 Use Cases & Examples

#### 1. Newsletter Content Research

**Analysts mapping what a publication covers over time.**
**Input:** A publication handle in Overview mode
**Output:** Every post with title, date, and engagement
**Use:** Spot themes, cadence, and top-performing topics

#### 2. Competitor Monitoring

**Marketers tracking rival newsletters.**
**Input:** Several competitor publications
**Output:** A unified table of their recent posts and engagement
**Use:** Benchmark posting frequency and audience response

#### 3. Author & Topic Analysis

**Researchers studying writers across publications.**
**Input:** Publications in Overview mode
**Output:** Bylines, word counts, and topics per post
**Use:** Identify prolific authors and trending subjects

#### 4. Engagement Benchmarking

**Growth teams measuring what resonates.**
**Input:** A publication archive
**Output:** Reactions, comments, and restacks per post
**Use:** Find the format and length that drive engagement

#### 5. Content Archiving

**Teams preserving a newsletter's back catalog.**
**Input:** A publication in Detail mode
**Output:** Full article HTML for every post
**Use:** Build a searchable internal archive

#### 6. Building a Reading Dataset

**Data teams creating a corpus for analysis.**
**Input:** Multiple publications in Detail mode
**Output:** Clean post text plus metadata
**Use:** Feed downstream NLP, search, or summarization

***

### 🔗 Integration Examples

#### JavaScript/Node.js

```javascript
import { ApifyClient } from 'apify-client';
const client = new ApifyClient({ token: 'YOUR_TOKEN' });

const run = await client.actor('sian.agency/substack-scraper').call({
  scrapeMode: 'overview',
  publications: ['bigtechnology'],
  maxResults: 50
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items[0]);
```

#### Python

```python
from apify_client import ApifyClient
client = ApifyClient('YOUR_TOKEN')

run = client.actor('sian.agency/substack-scraper').call(
    run_input={'scrapeMode': 'overview', 'publications': ['bigtechnology'], 'maxResults': 50}
)

for item in client.dataset(run['defaultDatasetId']).iterate_items():
    print(item)
```

#### cURL

```bash
curl -X POST 'https://api.apify.com/v2/acts/sian.agency~substack-scraper/runs?token=YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"scrapeMode": "detail", "publications": ["bigtechnology"], "maxResults": 20}'
```

#### Automation Workflows (N8N / Zapier / Make)

1. **Trigger**: Schedule or webhook
2. **HTTP Request**: Call the actor API
3. **Process**: Handle the JSON results
4. **Action**: Save, notify, or transform

***

### 📊 Performance & Pricing

#### FREE Tier (Try It Now)

- **25 posts** per run — full feature access, same quality
- No credit card required
- Perfect for testing and small projects

#### PAID Tier (Production Ready)

- **Unlimited** posts per run
- Faster, uninterrupted processing
- Pay-per-result: only charged for posts you actually extract

💰 **Pay only for what you extract** — predictable, transparent per-post pricing.

🔗 [View current pricing](https://apify.com/sian.agency/substack-scraper?fpr=sian)

***

### ❓ Frequently Asked Questions

**Q: How many posts can I process?**
A: FREE tier: 25 per run. PAID tier: unlimited.

**Q: Does it work with custom domains?**
A: Yes — handles, `*.substack.com` subdomains, and custom domains all work automatically.

**Q: Can I get the full article text?**
A: Yes — use Detail mode to capture the complete article HTML for each post.

**Q: What about paid or subscriber-only posts?**
A: Public metadata (title, author, engagement) is always available. Full body content for paid posts may be limited where the publication restricts it.

**Q: What output formats are available?**
A: JSON, CSV, and Excel — export directly from the Apify dataset.

**Q: Is this legal?**
A: It extracts only publicly available data. See the legal note below.

***

### 🐞 Troubleshooting

**No posts returned**

- Check the publication handle/domain is spelled correctly
- Try the `archive` endpoint with `sort: new`

**Fewer posts than expected**

- Raise `maxResults` and/or `maxPagesPerPublication`
- FREE tier is capped at 25 posts per run

**Missing article body**

- Full HTML is only captured in **Detail** mode
- Some paid posts limit body content

***

### ⚖️ Is it legal to scrape data?

Our actors are ethical and do not extract any private user data, such as email addresses, gender, or location. They only extract what the user has chosen to share publicly. We therefore believe that our actors, when used for ethical purposes by Apify users, are safe.

However, you should be aware that your results could contain personal data. Personal data is protected by the **GDPR** in the European Union and by other regulations around the world. You should not scrape personal data unless you have a legitimate reason to do so. If you're unsure whether your reason is legitimate, consult your lawyers.

You can also read Apify's blog post on the [legality of web scraping](https://blog.apify.com/is-web-scraping-legal/).

> **Trademark notice:** Substack is a trademark of Substack Inc. This actor is an independent tool and is not affiliated with, endorsed by, or sponsored by Substack Inc. All product names, logos, and brands are property of their respective owners.

***

### 🤝 Support

[![Telegram Support](https://img.shields.io/badge/Telegram-Support%20Group-0088cc?logo=telegram)](https://t.me/+vyh1sRE08sAxMGRi)

**Join our active support community**

- For issues or questions, open an issue in the actor's repository
- Check the [SIÁN Agency Store](https://apify.com/sian.agency?fpr=sian) for more automation tools
- 📧 <apify@sian-agency.online>

***

**Built by [SIÁN Agency](https://www.sian-agency.online)** | **[More Tools](https://apify.com/sian.agency?fpr=sian)**

# Actor input Schema

## `scrapeMode` (type: `string`):

🧭 **Choose what to extract:**

- **📰 Overview (cheap & fast):** paginate a publication's full archive and collect rich post metadata — titles, authors, dates, engagement, cover images. Best for bulk research.
- **📄 Detail (full content):** fetch each post's complete article HTML (body) on top of all overview fields. Best when you need the actual article text.

**TIP:** Start with Overview to map a publication, then run Detail on the posts you care about.

## `publications` (type: `array`):

📚 **Publications to scrape.** Each entry can be:

- a **handle** — `bigtechnology`
- a **Substack subdomain** — `bigtechnology.substack.com`
- a **custom domain** — `www.bigtechnology.com`

In **Overview** mode this is required. In **Detail** mode, leave it empty if you supply Post URLs below, or fill it to auto-discover and fetch the latest posts.

**BULK EDIT:** Click "Bulk edit" to paste many publications (one per line).

## `postUrls` (type: `array`):

🔗 **DETAIL MODE:** specific post URLs to fetch with full article HTML. Use public canonical links of the form `https://<publication>/p/<slug>`.

Leave empty to instead auto-discover posts from the Publications above. Ignored in Overview mode.

**BULK EDIT:** Click "Bulk edit" to paste many URLs (one per line).

## `maxResults` (type: `integer`):

🔢 **Cap the number of posts saved per run.**

**TIER-BASED LIMITS:**

- **FREE users:** up to 25 posts per run
- **PAID users:** unlimited

Deduplication and tier limits are applied before any post is fetched, so you are never charged for posts beyond your cap.

## `endpoint` (type: `string`):

🗂️ Which list endpoint to page through. `archive` is the default and carries the richest top-level fields; `posts` is an interchangeable alternative.

## `sort` (type: `string`):

↕️ Sort the archive by newest first (`new`) or by all-time most popular (`top`).

## `maxPagesPerPublication` (type: `integer`):

📑 Limit how many archive pages to page through per publication (each page is ~12 posts). Leave empty to crawl to the end of the archive (still capped by Max Posts Per Run).

## `useProxy` (type: `boolean`):

🌐 Route requests through a residential proxy. **Not required** — Substack's public data is reachable directly. Enable this only as a courtesy at very high volume, where it can reduce edge rate-limiting.

## Actor input object example

```json
{
  "scrapeMode": "overview",
  "publications": [
    "bigtechnology"
  ],
  "maxResults": 100,
  "endpoint": "archive",
  "sort": "new",
  "useProxy": false
}
```

# Actor output Schema

## `results` (type: `string`):

Scraped posts — titles, authors, engagement, images and (in Detail mode) full article HTML.

## `scrapingSummary` (type: `string`):

HTML summary showing extracted and failed results with key run metrics.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "publications": [
        "bigtechnology"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("sian.agency/substack-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "publications": ["bigtechnology"] }

# Run the Actor and wait for it to finish
run = client.actor("sian.agency/substack-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "publications": [
    "bigtechnology"
  ]
}' |
apify call sian.agency/substack-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=sian.agency/substack-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Substack Scraper — Posts, Authors & Newsletter Data",
        "description": "Substack newsletter scraper for any publication. Extract posts: title, subtitle, author, date, reactions, comments, restacks, word count, cover image — plus full article HTML in detail mode. Search by handle, subdomain or custom domain. Clean JSON/CSV, no-code, no API key needed.",
        "version": "1.0",
        "x-build-id": "cM2tVoxneGGSjIndP"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/sian.agency~substack-scraper/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-sian.agency-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/sian.agency~substack-scraper/runs": {
            "post": {
                "operationId": "runs-sync-sian.agency-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/sian.agency~substack-scraper/run-sync": {
            "post": {
                "operationId": "run-sync-sian.agency-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": {
                    "scrapeMode": {
                        "title": "🧭 Scrape Mode",
                        "enum": [
                            "overview",
                            "detail"
                        ],
                        "type": "string",
                        "description": "🧭 **Choose what to extract:**\n\n- **📰 Overview (cheap & fast):** paginate a publication's full archive and collect rich post metadata — titles, authors, dates, engagement, cover images. Best for bulk research.\n- **📄 Detail (full content):** fetch each post's complete article HTML (body) on top of all overview fields. Best when you need the actual article text.\n\n**TIP:** Start with Overview to map a publication, then run Detail on the posts you care about.",
                        "default": "overview"
                    },
                    "publications": {
                        "title": "📚 Publications",
                        "uniqueItems": true,
                        "type": "array",
                        "description": "📚 **Publications to scrape.** Each entry can be:\n\n- a **handle** — `bigtechnology`\n- a **Substack subdomain** — `bigtechnology.substack.com`\n- a **custom domain** — `www.bigtechnology.com`\n\nIn **Overview** mode this is required. In **Detail** mode, leave it empty if you supply Post URLs below, or fill it to auto-discover and fetch the latest posts.\n\n**BULK EDIT:** Click \"Bulk edit\" to paste many publications (one per line).",
                        "default": [
                            "bigtechnology"
                        ],
                        "items": {
                            "type": "string"
                        }
                    },
                    "postUrls": {
                        "title": "🔗 Post URLs (Detail mode)",
                        "uniqueItems": true,
                        "type": "array",
                        "description": "🔗 **DETAIL MODE:** specific post URLs to fetch with full article HTML. Use public canonical links of the form `https://<publication>/p/<slug>`.\n\nLeave empty to instead auto-discover posts from the Publications above. Ignored in Overview mode.\n\n**BULK EDIT:** Click \"Bulk edit\" to paste many URLs (one per line).",
                        "items": {
                            "type": "string"
                        }
                    },
                    "maxResults": {
                        "title": "🔢 Max Posts Per Run",
                        "minimum": 1,
                        "type": "integer",
                        "description": "🔢 **Cap the number of posts saved per run.**\n\n**TIER-BASED LIMITS:**\n- **FREE users:** up to 25 posts per run\n- **PAID users:** unlimited\n\nDeduplication and tier limits are applied before any post is fetched, so you are never charged for posts beyond your cap.",
                        "default": 100
                    },
                    "endpoint": {
                        "title": "🗂️ Archive Endpoint",
                        "enum": [
                            "archive",
                            "posts"
                        ],
                        "type": "string",
                        "description": "🗂️ Which list endpoint to page through. `archive` is the default and carries the richest top-level fields; `posts` is an interchangeable alternative.",
                        "default": "archive"
                    },
                    "sort": {
                        "title": "↕️ Sort Order",
                        "enum": [
                            "new",
                            "top"
                        ],
                        "type": "string",
                        "description": "↕️ Sort the archive by newest first (`new`) or by all-time most popular (`top`).",
                        "default": "new"
                    },
                    "maxPagesPerPublication": {
                        "title": "📑 Max Pages Per Publication",
                        "minimum": 1,
                        "type": "integer",
                        "description": "📑 Limit how many archive pages to page through per publication (each page is ~12 posts). Leave empty to crawl to the end of the archive (still capped by Max Posts Per Run)."
                    },
                    "useProxy": {
                        "title": "🌐 Use Residential Proxy",
                        "type": "boolean",
                        "description": "🌐 Route requests through a residential proxy. **Not required** — Substack's public data is reachable directly. Enable this only as a courtesy at very high volume, where it can reduce edge rate-limiting.",
                        "default": 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
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```
