> **For coding agents and LLMs:** This is one Social Fetch marketing page (markdown export). For API orientation start with [`/llms.txt`](https://www.socialfetch.dev/llms.txt); for auth and crawl rules use [`/agents.txt`](https://www.socialfetch.dev/agents.txt); for every operation use [`/llms-endpoints.txt`](https://www.socialfetch.dev/llms-endpoints.txt).

## This page

- **On-site (HTML):** <https://www.socialfetch.dev/platforms/substack/categories-categoryid-publications>
- **Markdown (.mdx) URL:** <https://www.socialfetch.dev/platforms/substack/categories-categoryid-publications.mdx>

---

# Substack Category Leaderboard API

One category's leaderboard in the ranking Substack uses, 25 publications a page.

`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`.

## Request

- **Endpoint:** `GET /v1/substack/categories/{categoryId}/publications`
- **Credits:** 1 credit
Failed requests are free
- **Input:** by category and ranking
- **Full reference:** [docs](https://www.socialfetch.dev/docs/api/v1/substack/categories/categoryid/publications/get)
- **Platform page:** [/platforms/substack](https://www.socialfetch.dev/platforms/substack)

## 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.