API Reference
Use Crawlora's Substack API endpoints to extract supported public Substack data as structured JSON. This documentation covers 19 active endpoints including List Substack categories, List the publications ranked in one Substack category, Browse the public Substack Explore surface, List a Substack category's bestseller leaderboard, and related APIs. Developers can use these endpoints for monitoring, enrichment, research dashboards, internal data pipelines, and agent-native workflows without maintaining platform-specific scraping code. Each endpoint page documents authentication, request parameters such as category_id, note_id, publication, slug, cURL examples, response examples, response schemas, errors, credit cost, and Playground testing. Send requests to the Crawlora API with an x-api-key header, review usage and plan limits on pricing, and test safe sample requests in Playground before moving the workflow into production.
Choose an endpoint, send an authenticated request with the x-api-key header, and inspect the normalized JSON response. The examples below use the public Crawlora API base URL and the same endpoint catalog used by Playground.
curl -X GET "https://api.crawlora.net/api/v1/substack/categories" \
-H "x-api-key: $CRAWLORA_API_KEY"These endpoint cards are generated from the active Crawlora endpoint catalog, including method, path, auth mode, credit cost, parameter summary, docs, and Playground links.
/substack/categoriesapiKey1 credit/requestReturns every public Substack category, with the category id required by /substack/category. Ids span two spaces: 32 categories use a numeric id and one uses the string id `podcast`. Both are accepted by /substack/category.
Required params: None
/substack/categoryapiKey3 credits/requestReturns one page of a category's public publication leaderboard. Each row carries the publication's subscriber signals and its full subscription offering (web plans with multi-currency pricing, App Store plans, and per-tier benefits). Subscriber totals are published to roughly three significant figures and are opt-in per writer; paid subscriber figures are only ever buckets. Upstream serves 25 publications per page and accepts pages 0-26, so at most 675 publications are reachable per category and type.
Required params: category_id:query
/substack/exploreapiKey3 credits/requestReturns one page of Substack's Explore surface. Explore is a feed of heterogeneous modules rather than a flat list, so each page returns the modules it contains and every module names its own type. Known module types are `trendingTopicsExplore` (trending topics and suggested searches), `trendingPostsExplore`, `newBestsellersExplore`, `videoSuggestionsExplore`, `categoryLeaderboard`, `comment` (a single Note) and `post` (a single post). Only the collections a module actually carries are populated. Pagination is cursor-based; early pages are curated shelves and later pages are individual Notes and posts.
Required params: None
/substack/leaderboardapiKey3 credits/requestReturns one page of a category's bestseller leaderboard, pairing each ranked publication with its author. This is a different surface from /substack/category: it exposes the trending ranking (the site's "Rising" tab), validates its ranking values rather than silently defaulting, accepts the extra cross-category id `bestseller`, and returns the author alongside the publication. Use a category_id from /substack/categories whose in_leaderboard is true. Upstream serves 25 rows per page and accepts pages 0-25.
Required params: category_id:query
/substack/noteapiKey3 credits/requestReturns one public Note with its author, engagement counts, and the post it links to when it has one. Notes are Substack's short-form social posts. note_id is the numeric id from a Note URL: in `/@handle/note/c-316240438` it is `316240438`.
Required params: note_id:query
/substack/note/repliesapiKey3 credits/requestReturns one page of public replies to a Note, each in the same shape as /substack/note. Pagination is cursor-based: pass the previous response's next_cursor back as cursor.
Required params: note_id:query
/substack/note/restacksapiKey3 credits/requestReturns one page of the Notes that restacked a given Note, each in the same shape as the single-Note endpoint. A restack may carry its own commentary in `body` or be a bare reshare with an empty body. Pagination is cursor-based.
Required params: note_id:query
/substack/notesapiKey3 credits/requestReturns one page of the public Notes feed for one tab. tab and type come as a pair from the Notes feed tabs endpoint. Pagination is cursor-based: pass the previous response's next_cursor back as cursor. Post-only rows in the upstream feed are omitted; every returned row is a Note.
Required params: None
/substack/notes/tabsapiKey1 credit/requestReturns every selectable tab for one surface. The two surfaces expose different tab sets: `feed` has 34 tabs (the main feed, the bestseller feed, and one per category) and `explore` has 33. Each row's id and type must be passed together to the matching feed endpoint, which rejects a tab whose type does not match.
Required params: None
/substack/postapiKey3 credits/requestReturns one public post with the extended metadata the archive listing omits, including word count, every credited byline, and podcast audio details where the post has them. Post bodies are not returned.
Required params: publication:query, slug:query
/substack/publicationapiKey3 credits/requestReturns a publication's public profile and its complete subscription offering: every purchasable web plan with per-currency pricing, the separately priced App Store plans, per-tier benefit copy, and the toggles governing which tiers are sold. Identify the publication by name (a subdomain such as semianalysis, or a custom domain such as www.thefp.com) or by numeric publication_id -- exactly one is required. Prefer publication_id when you have it: it reads a compact document, while resolving by name has to parse the publication's full homepage.
Required params: None
/substack/publication/contributorsapiKey3 credits/requestReturns one page of the writers credited on a publication, ranked as Substack ranks them. Rows include each writer's handle, profile URL, and bestseller badge tier, so a publication can be fanned out into individual /substack/user lookups. Large publications return several hundred contributors on the first page.
Required params: publication:query
/substack/publication/postsapiKey3 credits/requestReturns one page of a publication's public post archive with title, subtitle, canonical URL, publish date, engagement counts, and whether each post is paywalled. search filters the publication's own posts full-text; a query with no matches returns an empty list rather than the unfiltered archive.
Required params: publication:query
/substack/publication/recommendationsapiKey3 credits/requestReturns the publications a given publication recommends to its own readers, as a publication-to-publication graph. Useful for discovering publications beyond the 675-per-category ceiling on /substack/category. publication_id is the numeric id returned by /substack/publication, /substack/category, or /substack/user.
Required params: publication_id:query
/substack/searchapiKey3 credits/requestSearches posts across all of Substack and returns the publications that also matched, unlike /substack/publication/posts which searches within a single publication. Set focus_publication_id to additionally receive that one publication's own matching posts in focused_posts alongside the site-wide results.
Required params: query:query
/substack/userapiKey3 credits/requestReturns one public Substack profile: identity, the publications the writer contributes to, their publicly visible subscriptions, and every subscriber signal Substack publishes. total is opt-in per writer and rounded to roughly three significant figures; when a writer hides it, total_hidden is true and total is 0, which must not be read as zero subscribers. paid_rough, paid_rough_int, and paid_tier are buckets - no exact paid subscriber count is published anywhere. follower_count is exact but counts followers, not subscribers.
Required params: handle:query
/substack/user/activityapiKey3 credits/requestReturns one page of a user's public activity: the notes they wrote, posts they published, and items they liked, replied to, or restacked. types is an optional comma-separated filter accepting `note`, `post`, `like`, `replies` and `restack`; omit it for the default mixed feed. Each item's kind is the upstream's own finer-grained label, so filtering on `restack` returns both `comment_restack` and `post_restack` items. Pagination is cursor-based.
Required params: user_id:query
/substack/user/connectionsapiKey5 credits/requestReturns one of a user's public connection lists. Each entry is a full profile in the same shape as /substack/user, subscriber signals included. user_id is the numeric id returned by /substack/user. The upstream returns a bounded preview of each list rather than the complete membership.
Required params: user_id:query
/substack/user/searchapiKey3 credits/requestSearches public Substack profiles by name or handle. Each result carries the same subscriber signals as /substack/user, so a search enumerates writers without a second lookup per profile. Returns 20 profiles per page; use has_more rather than assuming a fixed depth, since result counts vary by query.
Required params: query:query
| Endpoint | API path | Method | Credits | Required params | Docs | Playground |
|---|---|---|---|---|---|---|
| List Substack categories | /substack/categories | GET | 1 credit/request | None | View docs | Try endpoint |
| List the publications ranked in one Substack category | /substack/category | GET | 3 credits/request | category_id:query | View docs | Try endpoint |
| Browse the public Substack Explore surface | /substack/explore | GET | 3 credits/request | None | View docs | Try endpoint |
| List a Substack category's bestseller leaderboard | /substack/leaderboard | GET | 3 credits/request | category_id:query | View docs | Try endpoint |
| Get one public Substack Note | /substack/note | GET | 3 credits/request | note_id:query | View docs | Try endpoint |
| List replies to a Substack Note | /substack/note/replies | GET | 3 credits/request | note_id:query | View docs | Try endpoint |
| List the Notes that restacked a Substack Note | /substack/note/restacks | GET | 3 credits/request | note_id:query | View docs | Try endpoint |
| Browse the public Substack Notes feed | /substack/notes | GET | 3 credits/request | None | View docs | Try endpoint |
| List the Substack feed tabs | /substack/notes/tabs | GET | 1 credit/request | None | View docs | Try endpoint |
| Get one public Substack post | /substack/post | GET | 3 credits/request | publication:query, slug:query | View docs | Try endpoint |
| Get a Substack publication and its subscription offering | /substack/publication | GET | 3 credits/request | None | View docs | Try endpoint |
| List a Substack publication's public contributors | /substack/publication/contributors | GET | 3 credits/request | publication:query | View docs | Try endpoint |
| List a Substack publication's public post archive | /substack/publication/posts | GET | 3 credits/request | publication:query | View docs | Try endpoint |
| List the publications one Substack publication recommends | /substack/publication/recommendations | GET | 3 credits/request | publication_id:query | View docs | Try endpoint |
| Search posts and publications across Substack | /substack/search | GET | 3 credits/request | query:query | View docs | Try endpoint |
| Get a public Substack writer profile | /substack/user | GET | 3 credits/request | handle:query | View docs | Try endpoint |
| List a Substack user's public activity | /substack/user/activity | GET | 3 credits/request | user_id:query | View docs | Try endpoint |
| List a Substack user's followers, following, or subscribers | /substack/user/connections | GET | 5 credits/request | user_id:query | View docs | Try endpoint |
| Search public Substack writer profiles | /substack/user/search | GET | 3 credits/request | query:query | View docs | Try endpoint |