Substack Publication Details API

Endpoint

GET /v1/substack/publication

Parameters

publication

Publication subdomain (lenny), host (lenny.substack.com, www.lennysnewsletter.com) or any URL on it (max 500 characters). Provide either publication or publication_id.

publication_id

Numeric publication ID, as returned in publication_id. Provide either publication or publication_id.

Response fields

publication

Publication data

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"

contributors

People who write for the publication

username

Contributor's handle

full_name

Display name

user_id

User ID

biography

Bio

profile_pic_url

Profile picture URL

bestseller_tier

Bestseller badge tier, 0 when none

is_byline_only

Whether the person only appears in bylines rather than as a publication member

url

Link to the profile

Example Request

curl "https://apidirect.io/v1/substack/publication?publication=lenny"   -H "X-API-Key: YOUR_API_KEY"

import requests

response = requests.get(
    "https://apidirect.io/v1/substack/publication",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"publication": "lenny"}
)
print(response.json())

Example Response

{
  "publication": {
    "author": "lenny",
    "author_id": "1849774",
    "author_name": "Lenny Rachitsky",
    "author_pic_url": "",
    "author_url": "https://substack.com/@lenny",
    "bestseller_tier": 10000,
    "contributors": [
      {
        "bestseller_tier": 0,
        "biography": "Student of products. I write to learn, share and meet kindred spirits ✨.  ",
        "full_name": "Kiyani",
        "is_byline_only": false,
        "profile_pic_url": "https://bucketeer-e05bbc84-baa3-437e-9518-adb32be77984.s3.amazonaws.com/public/images/48e9d3e5-91eb-41be-9701-420b01f6585f_313x321.jpeg",
        "url": "https://substack.com/@kiyani",
        "user_id": "3667529",
        "username": "kiyani"
      }
    ],
    "cover_image_url": "https://substack-post-media.s3.amazonaws.com/public/images/4a25905e-c484-4885-80fa-9c2e683e362b_592x592.png",
    "created_at": "2019-06-01 15:35:37",
    "custom_domain": "www.lennysnewsletter.com",
    "description": "Deeply researched product, growth, and career advice for product leaders, founders, and ambitious builders.\n",
    "domain": "substack.com",
    "first_post_date": "2019-06-14 15:00:48",
    "founding_plan_name": "",
    "has_chat": false,
    "has_podcast": true,
    "has_recommendations": false,
    "is_bestseller": true,
    "language": "en",
    "logo_url": "https://substackcdn.com/image/fetch/$s_!8MSN!,f_auto,q_auto:good,fl_progressive:steep/https%3A%2F%2Fsubstack-post-media.s3.amazonaws.com%2Fpublic%2Fimages%2F…",
    "logo_url_wide": "",
    "name": "Lenny's Newsletter",
    "paid_enabled": true,
    "paid_subscriber_band": "Tens of thousands of paid subscribers",
    "paid_subscriber_floor": 10000,
    "plans": [
      {
        "amount": 20.0,
        "currency": "USD",
        "interval": "month"
      }
    ],
    "podcast": null,
    "publication_id": "10845",
    "ranking_detail": "Tens of thousands of paid subscribers",
    "sections": [],
    "source": "Substack",
    "subdomain": "lenny",
    "subscriber_count": 1200000,
    "subscriber_count_label": "1.2M+",
    "twitter_handle": "lennysan",
    "type": "newsletter",
    "url": "https://www.lennysnewsletter.com"
  }
}

Frequently asked questions

Are subscriber counts exact?

No. Substack publishes a rounded free-subscriber figure (subscriber_count, with the badge in subscriber_count_label) and a band for paid subscribers (paid_subscriber_band). Small publications often show only a band, in which case subscriber_count is null.

Which identifiers work?

A subdomain (lenny), a Substack host (lenny.substack.com), a custom domain (www.lennysnewsletter.com), any URL on the publication, or its numeric publication_id.

How does pricing work?

You only pay for successful requests. The Substack Publication Details 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.