Search Substack Users API

Endpoint

GET /v1/substack/users

Parameters

query *

Search keyword (max 500 characters)

page

Page number, 1-4 (default: 1). 20 profiles per page

Response fields

users

Array of matching profiles

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

leaderboard

Leaderboard placement (category, category_id, rank, board), null when unranked

twitter_handle

X handle, empty 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

query

The search keyword

page

Current page number

has_next_page

Whether another page exists

count

Number of profiles returned

Example Request

curl "https://apidirect.io/v1/substack/users?query=lenny&page=1"   -H "X-API-Key: YOUR_API_KEY"

import requests

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

Example Response

{
  "count": 20,
  "has_next_page": true,
  "page": 1,
  "query": "lenny",
  "users": [
    {
      "bestseller_tier": 10000,
      "biography": "Writing • Angel investing • Advising",
      "date_joined": "2021-05-01 23:55:21",
      "follower_count": 1383966,
      "full_name": "Lenny Rachitsky",
      "is_bestseller": true,
      "leaderboard": {
        "board": "paid",
        "category": "Business",
        "category_id": 62,
        "rank": 1
      },
      "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",
      "subscriber_count": 1200000,
      "subscriber_count_label": "1.2M+",
      "twitter_handle": "lennysan",
      "url": "https://substack.com/@lenny",
      "user_id": "1849774",
      "username": "lenny"
    }
  ]
}

Frequently asked questions

Why only 4 pages?

Substack's profile search ends after about 75 results per query.

Are publications included?

Yes. A publication that has a Substack profile shows up alongside individual authors, with its subscriber badge in subscriber_count_label.

How does pricing work?

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