# Substack API

> Substack returns newsletter listings, public post text, and post details as a workflow and API.

Substack searches public newsletters by topic, returning names, authors, descriptions, links, and displayed subscriber counts; it needs a topic. List newsletter posts returns recent public post details for a newsletter; it needs a name or web address. Read post returns public text and post details; it needs a post link.

- Page: https://fous.com/workflows/substack
- Handle: `@substack`
- Category: [Social](https://fous.com/workflows/category/social)
- Source website: https://substack.com
- Last verified: Sep 29, 2026
- Fous is not affiliated with Substack.

## Methods

### List newsletter posts

Operation `list_newsletter_posts`, version 1. 1 credit per call.

List the latest public post details for a Substack newsletter by name or web address. Paid posts show public metadata only; some custom-domain newsletters may be unavailable.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `newsletter` | string | yes | `"lennysnewsletter.com"` | The newsletter name or web address, for example Lenny's Newsletter or lenny.substack.com. |
| `max_results` | integer | no | `3` | The maximum number of posts to return, for example 20. |

**Input schema**

```json
{
  "type": "object",
  "required": [
    "newsletter"
  ],
  "properties": {
    "newsletter": {
      "type": "string",
      "description": "The newsletter name or web address, for example Lenny's Newsletter or lenny.substack.com.",
      "examples": [
        "lennysnewsletter.com",
        "Lenny's Newsletter",
        "thegeneralist.substack.com"
      ]
    },
    "max_results": {
      "type": "integer",
      "default": 20,
      "maximum": 50,
      "minimum": 1,
      "description": "The maximum number of posts to return, for example 20.",
      "x-fous-developer": true,
      "examples": [
        3,
        5
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "newsletter": "lennysnewsletter.com",
      "max_results": 3
    },
    {
      "newsletter": "Lenny's Newsletter"
    },
    {
      "newsletter": "thegeneralist.substack.com",
      "max_results": 5
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `posts` | array |  |  |
| `posts[].likes` | integer or null | `326` |  |
| `posts[].title` | string | `"Advanced evals: How to find (and fix) hidden AI failures in your product"` |  |
| `posts[].access` | string | `"paid"` |  |
| `posts[].authors` | string or null | `"Hamel Husain, Shreya Shankar"` | Author names, separated by commas. |
| `posts[].post_id` | integer | `216168140` |  |
| `posts[].subtitle` | string or null | `"Why you should never skip error discovery"` |  |
| `posts[].post_link` | string | `"https://www.lennysnewsletter.com/p/advanced-evals-how-to-find-and-fix"` |  |
| `posts[].post_type` | string | `"article"` |  |
| `posts[].comment_count` | integer or null | `3` |  |
| `posts[].published_date` | string | `"2026-09-22"` |  |
| `posts[].cover_image_link` | string or null | `"https://substackcdn.com/image/fetch/$s_!0_d7!,f_auto,q_auto:good,fl_progressive:steep/https%3A%2F%2Fsubstack-post-media` |  |
| `newsletter_link` | string | `"https://www.lennysnewsletter.com"` |  |
| `newsletter_name` | string | `"Lenny's Newsletter"` |  |

**Example input**

```json
{
  "newsletter": "lennysnewsletter.com",
  "max_results": 3
}
```

**Example output**

```json
{
  "posts": [
    {
      "likes": 326,
      "title": "Advanced evals: How to find (and fix) hidden AI failures in your product",
      "access": "paid",
      "authors": "Hamel Husain, Shreya Shankar",
      "post_id": 216168140,
      "subtitle": "Why you should never skip error discovery",
      "post_link": "https://www.lennysnewsletter.com/p/advanced-evals-how-to-find-and-fix",
      "post_type": "article",
      "comment_count": 3,
      "published_date": "2026-09-22",
      "cover_image_link": "https://substackcdn.com/image/fetch/$s_!0_d7!,f_auto,q_auto:good,fl_progressive:steep/https%3A%2F%2Fsubstack-post-media.s3.amazonaws.com%2Fpublic%2Fimages%2F6f6018cf-fa53-4f40-99d9-b1c9980dd031_1456x9…"
    },
    {
      "likes": 413,
      "title": "60+ new creative growth ideas",
      "access": "paid",
      "authors": "Tom Orbach",
      "post_id": 214360366,
      "subtitle": "How to stand out when everyone is running the same playbook",
      "post_link": "https://www.lennysnewsletter.com/p/60-creative-growth-ideas",
      "post_type": "article",
      "comment_count": 6,
      "published_date": "2026-09-15",
      "cover_image_link": "https://substackcdn.com/image/fetch/$s_!NVVg!,f_auto,q_auto:good,fl_progressive:steep/https%3A%2F%2Fsubstack-post-media.s3.amazonaws.com%2Fpublic%2Fimages%2F20cbbe62-5c82-4d4f-a316-de9b885e56f2_1456x9…"
    }
  ],
  "newsletter_link": "https://www.lennysnewsletter.com",
  "newsletter_name": "Lenny's Newsletter"
}
```

### Read post

Operation `read_post`, version 1. 1 credit per call.

Read the text and details of a public Substack post from its link. Paid posts show only the public preview; word count may describe the whole post.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `post` | string | yes | `"https://www.oneusefulthing.org/p/the-twilight-of-the-chatbots"` | The link to the newsletter post, for example https://www.oneusefulthing.org/p/the-twilight-of-the-chatbots. |

**Input schema**

```json
{
  "type": "object",
  "required": [
    "post"
  ],
  "properties": {
    "post": {
      "type": "string",
      "description": "The link to the newsletter post, for example https://www.oneusefulthing.org/p/the-twilight-of-the-chatbots.",
      "examples": [
        "https://www.oneusefulthing.org/p/the-twilight-of-the-chatbots",
        "https://msolney.substack.com/p/im-changing-my-substack-paid-subscribers",
        "https://substack.com/home/post/p-216505817"
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "post": "https://www.oneusefulthing.org/p/the-twilight-of-the-chatbots"
    },
    {
      "post": "https://msolney.substack.com/p/im-changing-my-substack-paid-subscribers"
    },
    {
      "post": "https://substack.com/home/post/p-216505817"
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `likes` | integer or null | `799` | Number of likes. |
| `title` | string or null | `"The twilight of the chatbots"` | Post title. |
| `access` | string | `"free"` | Whether the post is free or paid. |
| `authors` | array |  | Names of the post authors. |
| `subtitle` | string or null | `"How work changes along the exponential"` | Post subtitle, if given. |
| `post_link` | string | `"https://www.oneusefulthing.org/p/the-twilight-of-the-chatbots"` | Link to the post. |
| `paragraphs` | array |  | The publicly available post text, as plain-text paragraphs. |
| `word_count` | integer or null | `1271` | Post word count, including gated text if the post is paid. |
| `comment_count` | integer or null | `103` | Number of comments. |
| `published_date` | string or null | `"2026-06-30"` | Date the post was published. |
| `newsletter_name` | string or null | `"One Useful Thing"` | Name of the newsletter. |
| `cover_image_link` | string or null | `"https://substackcdn.com/image/fetch/$s_!CQgP!,f_auto,q_auto:good,fl_progressive:steep/https%3A%2F%2Fsubstack-post-media` | Cover image link, when present. |
| `full_text_available` | boolean | `true` | Whether the full post text is publicly available. |

**Example input**

```json
{
  "post": "https://www.oneusefulthing.org/p/the-twilight-of-the-chatbots"
}
```

**Example output**

```json
{
  "likes": 799,
  "title": "The twilight of the chatbots",
  "access": "free",
  "authors": [
    "Ethan Mollick"
  ],
  "subtitle": "How work changes along the exponential",
  "post_link": "https://www.oneusefulthing.org/p/the-twilight-of-the-chatbots",
  "paragraphs": [
    "If you feel like things are accelerating in AI, you are probably right. Better AI models from the leading American AI labs have been releasing more quickly than ever (though government interventions s…",
    "But it isn't just release timing. The evidence points to accelerating capability gains as well (though the frontier stays jagged, and AIs remain weak in many places). This is especially obvious when w…",
    "Another organization doing similar experiments, Epoch , recently found Opus 4.7, working on its own for 14 hours, was able to build a software package that would take 2-17 weeks of human engineering w…"
  ],
  "word_count": 1271,
  "comment_count": 103,
  "published_date": "2026-06-30",
  "newsletter_name": "One Useful Thing",
  "cover_image_link": "https://substackcdn.com/image/fetch/$s_!CQgP!,f_auto,q_auto:good,fl_progressive:steep/https%3A%2F%2Fsubstack-post-media.s3.amazonaws.com%2Fpublic%2Fimages%2F8215c2ac-ba16-483d-a53d-2957f2add233_1376x8…",
  "full_text_available": true
}
```

### Search newsletters

Operation `search_newsletters`, version 1. 1 credit per call.

Find public Substack newsletters about a topic in Substack search order. Subscriber counts are null when Substack does not display a count.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `topic` | string | yes | `"product management"` | Words describing newsletters to find, for example, product management. |
| `max_results` | integer | no | `50` | Maximum newsletters to return, for example, 20. |

**Input schema**

```json
{
  "type": "object",
  "required": [
    "topic"
  ],
  "properties": {
    "topic": {
      "type": "string",
      "minLength": 1,
      "description": "Words describing newsletters to find, for example, product management.",
      "examples": [
        "product management",
        "personal finance"
      ]
    },
    "max_results": {
      "type": "integer",
      "default": 20,
      "maximum": 50,
      "minimum": 1,
      "description": "Maximum newsletters to return, for example, 20.",
      "x-fous-developer": true,
      "examples": [
        50,
        5
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "topic": "product management"
    },
    {
      "topic": "personal finance",
      "max_results": 50
    },
    {
      "topic": "product management",
      "max_results": 5
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `newsletters` | array |  | Matching newsletters in Substack search order. |
| `newsletters[].name` | string | `"Product Management with Mani Grewal"` |  |
| `newsletters[].author` | string or null | `"Product Management with Mani"` |  |
| `newsletters[].description` | string or null | `"AI Literacy Advocate \| Product Leader \| Author \| Career Coach \| Speaker on Women, AI & the Future of Work"` |  |
| `newsletters[].logo_image_link` | string or null | `"https://substackcdn.com/image/fetch/$s_!KoiO!,f_auto,q_auto:good,fl_progressive:steep/https%3A%2F%2Fsubstack-post-media` |  |
| `newsletters[].newsletter_link` | string | `"https://productmanagementwithmani.substack.com"` |  |
| `newsletters[].subscriber_count` | string or null | `"Over 7,000 subscribers"` | Subscriber count as shown on Substack, or null when not displayed. |
| `newsletters[].offers_paid_subscriptions` | boolean | `true` |  |

**Example input**

```json
{
  "topic": "product management",
  "max_results": 5
}
```

**Example output**

```json
{
  "newsletters": [
    {
      "name": "Product Management with Mani Grewal",
      "author": "Product Management with Mani",
      "description": "AI Literacy Advocate | Product Leader | Author | Career Coach | Speaker on Women, AI & the Future of Work",
      "logo_image_link": "https://substackcdn.com/image/fetch/$s_!KoiO!,f_auto,q_auto:good,fl_progressive:steep/https%3A%2F%2Fsubstack-post-media.s3.amazonaws.com%2Fpublic%2Fimages%2F387639fb-ca1d-4b0d-9222-f2b6fb7ef069_688x68…",
      "newsletter_link": "https://productmanagementwithmani.substack.com",
      "subscriber_count": null,
      "offers_paid_subscriptions": true
    },
    {
      "name": "Technical Product Manager",
      "author": "Technical Product Manager",
      "description": "I am an ex-PhD/developer and am now a Lead PM at Booking.com. I write about hard skills one should master to excel in a product management career. Every week, I take a challenge from day-to-day PM lif…",
      "logo_image_link": "https://substackcdn.com/image/fetch/$s_!VPEl!,f_auto,q_auto:good,fl_progressive:steep/https%3A%2F%2Fsubstack-post-media.s3.amazonaws.com%2Fpublic%2Fimages%2F7bb3b667-4b21-430b-93aa-038f7138bb8b_320x32…",
      "newsletter_link": "https://pmskills.substack.com",
      "subscriber_count": "Over 7,000 subscribers",
      "offers_paid_subscriptions": false
    },
    {
      "name": "Product Management Society",
      "author": "Gabriela Naumnik",
      "description": "Unlock the PM Code: Transform from Zero to Product Hero, One Insightful Read at a Time! 🚀 (Articles are posted twice per week)",
      "logo_image_link": "https://substackcdn.com/image/fetch/$s_!cQtC!,f_auto,q_auto:good,fl_progressive:steep/https%3A%2F%2Fsubstack-post-media.s3.amazonaws.com%2Fpublic%2Fimages%2F3567227f-9c5e-4bca-89fe-3e7e564d8461_1280x1…",
      "newsletter_link": "https://productmanagementsociety.substack.com",
      "subscriber_count": null,
      "offers_paid_subscriptions": false
    }
  ]
}
```

## Quick start

Call the API with a Fous API key (`FOUS_API_KEY`). To create one, turn on Developer mode in Fous Studio, then open Keys & connections → API keys (https://app.fous.com/keys).

```bash
# First set your key: export FOUS_API_KEY='YOUR_FOUS_API_KEY'
: "${FOUS_API_KEY:?Set FOUS_API_KEY before running this example}"

curl 'https://api.fous.com/v1/query' \
  --fail-with-body --silent --show-error --max-time 120 \
  -H "Authorization: Bearer $FOUS_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "api": "@substack",
  "visibility": "public",
  "operation": "list_newsletter_posts",
  "version": 1,
  "input": {
    "newsletter": "lennysnewsletter.com",
    "max_results": 3
  },
  "response": {
    "format": "json"
  }
}'
```

```python
# Save as fous.py and run with python3 fous.py. No packages needed.
# First set your key: export FOUS_API_KEY='YOUR_FOUS_API_KEY'
import json
import os
import urllib.error
import urllib.request

api_key = os.environ.get("FOUS_API_KEY")
if not api_key:
    raise RuntimeError("Set FOUS_API_KEY before running this example")

body = json.loads("{\n  \"api\": \"@substack\",\n  \"visibility\": \"public\",\n  \"operation\": \"list_newsletter_posts\",\n  \"version\": 1,\n  \"input\": {\n    \"newsletter\": \"lennysnewsletter.com\",\n    \"max_results\": 3\n  },\n  \"response\": {\n    \"format\": \"json\"\n  }\n}")
request = urllib.request.Request(
    "https://api.fous.com/v1/query",
    data=json.dumps(body).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    method="POST",
)
try:
    with urllib.request.urlopen(request, timeout=120) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    raise RuntimeError(f"HTTP {error.code}: {error.read().decode('utf-8', errors='replace')}") from error
if result.get("success") is False:
    raise RuntimeError(result.get("error", {}).get("message", "Request failed"))
print(json.dumps(result["data"]["output"], indent=2))
```

```typescript
// Save as fous.mts and run with npx tsx fous.mts.
// First set your key: export FOUS_API_KEY='YOUR_FOUS_API_KEY'
const apiKey = process.env.FOUS_API_KEY;
if (!apiKey) throw new Error("Set FOUS_API_KEY before running this example");

const response = await fetch("https://api.fous.com/v1/query", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  signal: AbortSignal.timeout(120_000),
  body: JSON.stringify({
  "api": "@substack",
  "visibility": "public",
  "operation": "list_newsletter_posts",
  "version": 1,
  "input": {
    "newsletter": "lennysnewsletter.com",
    "max_results": 3
  },
  "response": {
    "format": "json"
  }
}),
});
type ApiResult = { success: boolean; data?: { output: unknown }; error?: { message: string } };
const result: ApiResult = await response.json();
if (!response.ok || result.success === false) {
  throw new Error(result.error?.message ?? `HTTP ${response.status}`);
}
if (!result.data) throw new Error("Missing API response data");
console.log(result.data.output);
```

Or describe the data in plain language: send `{"api":"@substack","prompt":"Describe the data you need, with every detail"}` to the same URL. Fous fills in the input, runs the method that fits and returns only the fields you asked for; `data.route.calls[].request` is the exact call it made. Routing is free; the run costs the same.

## Use cases

- Find public newsletters about a topic
- Compare newsletter descriptions and displayed subscriber counts
- Track recent posts from selected newsletters
- Review public post text and publication details
- Identify posts with paid access

## FAQ

### Is Fous affiliated with Substack?

No. Fous is not affiliated with Substack. This workflow reads the public substack.com website and returns its data.

### How much does it cost?

Each run costs 1 credit. With pay-as-you-go, a credit costs 1¢; monthly plans cost less per credit.

### Do I need a Substack account?

No. You only need a Fous account.

### How current is the data?

Fous gets the data from substack.com when you run it; repeating the same request within a day may return the saved result. Fous checks this workflow automatically; it last passed a check on Sep 29, 2026.

### How can I find newsletters about a topic?

Use Search newsletters with a topic to find matching public newsletters in Substack search order.

### What posts has a newsletter published recently?

Use List newsletter posts with a newsletter name or web address to get recent public post details.

### Can I read a post's text?

Use Read post with its link to get publicly available post text and details. Paid posts show only the public preview.

## Related

- [Medium API](https://fous.com/workflows/medium.md): Medium returns public writer, publication, and topic articles, including newest posts and weekly popular picks, plus readable article text; member-only stories remain limited to visible previews.
- [Telegram API](https://fous.com/workflows/telegram.md): Telegram provides public channel details and the latest posts visible in public previews, with media and view totals that may be rounded or approximate.
- [Mastodon API](https://fous.com/workflows/mastodon.md): Mastodon provides public profiles and recent public posts, including hashtag posts, but excludes private and unlisted posts and may limit visibility to accounts known to mastodon.social or a selected server.
- [Threads API](https://fous.com/workflows/threads.md): Threads provides public profiles and posts, including recent posts, engagement and replies; private or login-only content is excluded, and replies may be limited to 10.
- [Reddit API](https://fous.com/workflows/reddit.md): Reddit returns searchable public posts, community feeds/details, user profiles and recent activity, posts with up to 200 comments; unavailable content limits results; Top defaults weekly.
- [X API](https://fous.com/workflows/x.md): X returns public profile details and public posts with author, media, and engagement; deleted, protected, or unavailable posts cannot be retrieved.
- [Instagram API](https://fous.com/workflows/instagram.md): Instagram provides public photos, videos, profiles, exact headline counts, bio links, and profile pictures, plus recent public posts and reels; some profiles or posts require login, and view counts may be unavailable.
- [Bluesky API](https://fous.com/workflows/bluesky.md): Bluesky provides public profile details and latest posts, plus searches of up to 100 matching public posts; search results may lag behind new posts.
- [All Social workflows](https://fous.com/workflows/category/social)