Substack Category Leaderboard API
One category's leaderboard in the ranking Substack uses, 25 publications a page.
GET /v1/substack/categories/{categoryId}/publications1 credit Failed requests are free
About this endpoint
GET /v1/substack/categories/{categoryId}/publications lists one page of a category leaderboard. categoryId is a numeric id from categories.list. ranking is all, paid or trending, and page is 0-based, runs to 20 and returns 25 publications a page. Page 20 is the last page even when Substack still reports more. A page past 20 returns an empty list with hasMore: false.
data.publications[] carries publication summaries, data.title is the category's title, data.ranking echoes the ranking, and data.categoryId names the category. data.page reports page, hasMore and nextPage. lookupStatus is found or not_found.
Substack Category Leaderboard API FAQ
What do the rankings mean?
all is Substack's overall leaderboard, paid ranks by paid readership and trending ranks by Substack's trending view. The route does not invent an order.
How many publications per page?
Twenty-five. Follow page.nextPage while page.hasMore is true.
Where do I find the category id?
Call categories.list and read data.categories[].id. An unknown id comes back as lookupStatus: not_found.
How many credits does a leaderboard page cost?
Pricing is documented on the operation in the API registry (shown on this page). Confirm on every response with meta.creditsCharged: that field is the billing source of truth.
Other Substack endpoints
- PublicationGET /v1/substack/publications/{publication}
- PostsGET /v1/substack/publications/{publication}/posts
- Post bodiesGET /v1/substack/publications/{publication}/posts/bodies
- Post indexGET /v1/substack/publications/{publication}/posts/index
- Search postsGET /v1/substack/publications/{publication}/posts/search
- RecommendationsGET /v1/substack/publications/{publication}/recommendations
- Publication feedGET /v1/substack/publications/{publication}/feed
- PostGET /v1/substack/posts/{post}