Substack Category Publications API

Endpoint

GET /v1/substack/category/publications

Parameters

category *

Category ID or slug, e.g. 4 or technology. See /docs/substack-category-ids

tier

all, paid or rising (bestsellers: rising; podcasts: all or paid)

page

Page number (default: 1), 25 publications per page. Up to 21 pages; rising 10; bestsellers and podcasts 4

Response fields

publications

Ranked publications

rank

Position on the board

publication_id

Publication ID

name

Publication name

subdomain

Substack subdomain (<subdomain>.substack.com)

url

Publication home URL (the custom domain when it has one)

custom_domain

Custom domain, empty when none

description

Publication tagline

logo_url

Logo URL

cover_image_url

Cover image URL, empty when none

author

Primary author's handle

author_name

Primary author's display name

author_id

Primary author's user ID

author_url

Link to the primary author's profile

subscriber_count

Free subscriber count as Substack displays it (rounded, e.g. 1200000); null when the publication hides it

subscriber_count_label

The displayed subscriber badge, e.g. 1.2M+, or a band such as Thousands of subscribers

ranking_detail

Substack's ranking note: the paid-subscriber band for established publications or a launch note such as Launched a year ago for new ones; empty when not shown

paid_subscriber_band

Paid subscriber band, e.g. Tens of thousands of paid subscribers; empty when Substack shows none

paid_subscriber_floor

Lower bound of the paid band (100, 1000, 10000), 0 when none

bestseller_tier

Bestseller badge tier: 0, 100, 1000 or 10000 paid subscribers

is_bestseller

Whether the publication carries a bestseller badge

paid_enabled

Whether paid subscriptions are enabled

plans

Subscription prices (interval, amount, currency)

has_podcast

Whether the publication has a podcast

podcast

The publication's podcast (title, description, art_url, host, is_free, is_subscriber_only), null when none

sections

The publication's sections (section_id, name, slug, is_podcast)

author_pic_url

Primary author's profile picture URL

logo_url_wide

Wide logo URL, empty when none

founding_plan_name

Name of the founding tier, empty when none

has_recommendations

Whether the publication recommends other publications

has_chat

Whether subscriber chat is enabled

language

Language code

type

newsletter or podcast

twitter_handle

The publication's X handle, empty when none

created_at

Date the publication was created (UTC)

first_post_date

Date of the first post (UTC)

source

"Substack"

domain

"substack.com"

Example Request

curl "https://apidirect.io/v1/substack/category/publications?category=technology&page=1"   -H "X-API-Key: YOUR_API_KEY"

import requests

response = requests.get(
    "https://apidirect.io/v1/substack/category/publications",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"category": "technology", "page": 1}
)
print(response.json())

Example Response

{
  "category": {
    "category_id": 4,
    "name": "Technology"
  },
  "count": 25,
  "has_next_page": true,
  "page": 1,
  "publications": [
    {
      "author": "bytebytego",
      "author_id": "22329494",
      "author_name": "Alex Xu",
      "author_pic_url": "",
      "author_url": "https://substack.com/@bytebytego",
      "bestseller_tier": 0,
      "cover_image_url": "https://substack-post-media.s3.amazonaws.com/public/images/a4e1c1bd-03ee-4126-b3e4-19553b2d2fc6_1279x821.png",
      "created_at": "2022-03-27 03:36:45",
      "custom_domain": "blog.bytebytego.com",
      "description": "Explain complex systems with simple terms, from the authors of the best-selling system design book series. Join over 1,000,000 friendly readers.",
      "domain": "substack.com",
      "first_post_date": "2021-11-25 17:31:00",
      "founding_plan_name": "",
      "has_chat": false,
      "has_podcast": false,
      "has_recommendations": false,
      "is_bestseller": false,
      "language": "en",
      "logo_url": "https://substackcdn.com/image/fetch/$s_!1eXV!,f_auto,q_auto:good,fl_progressive:steep/https%3A%2F%2Fbucketeer-e05bbc84-baa3-437e-9518-adb32be77984.s3.amazona…",
      "logo_url_wide": "",
      "name": "ByteByteGo Newsletter",
      "paid_enabled": true,
      "paid_subscriber_band": "",
      "paid_subscriber_floor": 0,
      "plans": [
        {
          "amount": 15.0,
          "currency": "USD",
          "interval": "month"
        }
      ],
      "podcast": null,
      "publication_id": "817132",
      "rank": 1,
      "ranking_detail": "",
      "sections": [],
      "source": "Substack",
      "subdomain": "bytebytego",
      "subscriber_count": null,
      "subscriber_count_label": "",
      "twitter_handle": "alexxubyte",
      "type": "newsletter",
      "url": "https://blog.bytebytego.com"
    }
  ],
  "tier": "all"
}

Frequently asked questions

What do the tiers mean?

paid ranks publications by paid subscriptions, rising is Substack's board of publications climbing fastest, and all mixes paid and free as Substack's category page does.

How do I get the site-wide boards?

Pass category=bestsellers for New Bestsellers (a rising list) or category=podcasts for Podcast Bestsellers (all or paid).

How does pricing work?

You only pay for successful requests. The Substack Category Publications API costs $0.003 per request. There are no monthly fees or commitments. You get 50 free requests per endpoint every month.

Do I need a credit card to start?

No. You can sign up and use the free tier (50 requests/endpoint/month) without adding a payment method. You only need to add a card when you want to exceed the free tier.

Are there rate limits?

Yes, there's a concurrency limit of 10 simultaneous requests per endpoint per user. If you need more, just get in touch.