# Substack Newsletter Leaderboards API

> Substack bestseller and trending newsletters in 35 categories, with publication and author details

- Vendor: `substacknewsletterleaderboards` · version 1.0 · category News & Media · tags substack api, newsletter rankings api, top newsletters api, substack leaderboard api, creator economy api, newsletter discovery api
- Datasource: custom HTTP routes
- Marketplace page: https://apiclay.com/api/substacknewsletterleaderboards
- This document: https://apiclay.com/docs/substacknewsletterleaderboards.md
- OpenAPI 3.1: https://apiclay.com/api/substacknewsletterleaderboards/openapi.json
- MCP: connect https://api.apiclay.com/v1/mcp (see https://apiclay.com/llms.txt), then `apiclay_describe_api` with vendor `substacknewsletterleaderboards`
- Updated: 2026-11-18

## About

## Substack Newsletter Leaderboards API

The leaderboards behind Substack's discovery pages: the 35 categories (culture, politics, technology, business, finance, sports and more) with their descriptions, and for each category the top 25 paid bestsellers or the trending newsletters, each with the publication (name, subdomain, custom domain, logo, description, language, launch date, payments on) and its author (name, handle, bio, photo).

Data comes from **substack.com** (https://substack.com). Every route calls the source's own public API and returns it unchanged.

Typical flow: `/categories` for the category ids, then `/leaderboard?category=96&amp;ranking=paid` or `ranking=trending`.

### Routes

#### GET `/categories` - Categories
No parameters.

Returns: Array of 35 categories: `id`, `name`, `slug`, `emoji`, `rank`, `leaderboard_description` and subcategories.

#### GET `/leaderboard` - Leaderboard
| Param | In | Type | Required | Description |
|---|---|---|---|---|
| category | path | string | yes | Category `id` from `/categories`, e.g. `96` (Culture). |
| ranking | path | string | yes | `paid` (bestsellers) or `trending`. |

Returns: `title`, `items` (25, ranked) each with `publication` (`name`, `subdomain`, `custom_domain`, `logo_url`, `hero_text`, `language`, `created_at`, `payments_state`) and `user` (`name`, `handle`, `bio`, `photo_url`), and `more`.

### Caveats

- Rankings are Substack's own and change daily; subscriber counts are not included. Publication and author details are what the writers made public on Substack.
- Upstream responses can change over time. Verify fields before relying on them.
- Not affiliated with or endorsed by substack.com.

## Pricing

- Pay as you go: 0.0012 credits/request
- Trial: 1 free requests per buyer
- Billing order: trial requests -> subscribed plan requests -> pay as you go. 1 credit's USD value is shown on the marketplace page.

## HTTP routes

Only the public, buyer-facing parts of each route are listed; vendor-side credentials stay on the gateway.

### GET /categories — Categories
- Gateway: `GET https://api.apiclay.com/v1/api/substacknewsletterleaderboards/categories`
- Upstream proxy: ApiClay proxy paid by the vendor (data cap 2 MB per call). Fetched through an ApiClay proxy paid by the vendor; a response larger than the route's data cap fails with 502 and is refunded in full.

### GET /leaderboard — Leaderboard
- Gateway: `GET https://api.apiclay.com/v1/api/substacknewsletterleaderboards/leaderboard`
- Public query params: `category` (string, required), `ranking` (string, required)
- Upstream proxy: ApiClay proxy paid by the vendor (data cap 2 MB per call). Fetched through an ApiClay proxy paid by the vendor; a response larger than the route's data cap fails with 502 and is refunded in full.

## Call example

```bash
curl -X GET "https://api.apiclay.com/v1/api/substacknewsletterleaderboards/categories" \
  -H "token: <YOUR_APICLAY_TOKEN>"
```

Index of every published API: https://apiclay.com/llms.txt
