Substack User Profile API

Endpoint

GET /v1/substack/user

Parameters

username

Substack handle, e.g. lenny, with or without a leading @ (max 100 characters). Provide one of username, user_id or url.

user_id

Numeric Substack user ID, as returned in user_id. Provide one of username, user_id or url.

url

Profile URL, e.g. https://substack.com/@lenny (max 500 characters). Provide one of username, user_id or url.

Response fields

user

Profile data

username

Substack handle

full_name

Display name

user_id

User ID (pass it as user_id to the user endpoints)

biography

Profile bio

profile_pic_url

Profile picture URL

follower_count

Number of followers

subscriber_count

Rounded subscriber count of the primary publication, 0 when not shown

subscriber_count_label

The displayed subscriber badge, e.g. 1.2M+

bestseller_tier

Bestseller badge tier: 0, 100, 1000 or 10000

is_bestseller

Whether the author carries a bestseller badge

paid_subscriber_band

Paid subscriber band of the primary publication, e.g. Tens of thousands, empty when not shown

paid_subscriber_floor

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

primary_publication

The author's main publication (publication_id, name, subdomain, url, logo_url)

date_joined

Profile creation date and time (UTC)

url

Link to the profile

publications

Publications the author writes for (publication_id, name, subdomain, url, logo_url, role)

links

Links on the profile (type, label, url)

twitter_handle

Connected X handle, empty when none

leaderboard

Leaderboard placement (category, category_id, rank, board), or null

subscriptions_count

Number of publications the author publicly subscribes to

slug

Profile slug, as in substack.com/profile/<id>-<slug>

recommendation_count

Number of publications the author's primary publication recommends

has_guest_posts

Whether the author has guest posts on other publications

subscriptions

The publications the author publicly subscribes to (publication_id, name, subdomain, url, logo_url, plan)

plan

free, paid or comp (a complimentary paid subscription)

has_posts

Whether the author has published posts

Example Request

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

import requests

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

Example Response

{
  "user": {
    "bestseller_tier": 10000,
    "biography": "Writing • Angel investing • Advising",
    "date_joined": "2021-05-01 23:55:21",
    "follower_count": 1383966,
    "full_name": "Lenny Rachitsky",
    "has_guest_posts": true,
    "has_posts": true,
    "is_bestseller": true,
    "leaderboard": {
      "board": "paid",
      "category": "Business",
      "category_id": 62,
      "rank": 1
    },
    "links": [
      {
        "label": "",
        "type": "twitter",
        "url": "https://x.com/lennysan"
      }
    ],
    "paid_subscriber_band": "Tens of thousands",
    "paid_subscriber_floor": 10000,
    "primary_publication": {
      "logo_url": "https://substack-post-media.s3.amazonaws.com/public/images/441213db-4824-4e48-9d28-a3a18952cbfc_592x592.png",
      "name": "Lenny's Newsletter",
      "publication_id": "10845",
      "subdomain": "lenny",
      "url": "https://www.lennysnewsletter.com"
    },
    "profile_pic_url": "https://bucketeer-e05bbc84-baa3-437e-9518-adb32be77984.s3.amazonaws.com/public/images/afba5161-65bb-4d99-8d6b-cce660917fa1_1540x1540.png",
    "publications": [
      {
        "logo_url": "https://substack-post-media.s3.amazonaws.com/public/images/441213db-4824-4e48-9d28-a3a18952cbfc_592x592.png",
        "name": "Lenny's Newsletter",
        "publication_id": "10845",
        "role": "admin",
        "subdomain": "lenny",
        "url": "https://www.lennysnewsletter.com"
      }
    ],
    "recommendation_count": 11,
    "slug": "lenny-rachitsky",
    "subscriber_count": 1200000,
    "subscriber_count_label": "1.2M+",
    "subscriptions": [
      {
        "logo_url": "https://substack-post-media.s3.amazonaws.com/public/images/cc7ca458-37ff-4275-a738-d25e07f498c2_1280x1280.png",
        "name": "@jasmine’s substack",
        "plan": "paid",
        "publication_id": "6027",
        "subdomain": "jasmine",
        "url": "https://jasmi.news"
      }
    ],
    "subscriptions_count": 109,
    "twitter_handle": "lennysan",
    "url": "https://substack.com/@lenny",
    "user_id": "1849774",
    "username": "lenny"
  }
}

Frequently asked questions

What is the difference between followers and subscribers?

follower_count is the exact number of Substack accounts following the author. subscriber_count is the rounded free-subscriber figure Substack displays for their primary publication (e.g. 1200000 for a "1.2M+" badge); exact subscriber numbers are not public.

Can I look up a profile by ID?

Yes. Pass user_id, or a profile URL of the form https://substack.com/profile/1849774-lenny-rachitsky. user_id is returned by every endpoint that names a person.

How does pricing work?

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