Substack Recommendations API
The publications a publication recommends, plus Substack's ordered top list.
GET /v1/substack/publications/{publication}/recommendations1 credit Failed requests are free
About this endpoint
GET /v1/substack/publications/{publication}/recommendations returns the publications that a publication recommends. limit is 1 to 99 and defaults to 50.
data.recommendations[] carries id, recommendedPublicationId, recommendingPublicationId, createdAt, blurb and a publication summary. data.top[] is Substack's ordered list, with rows of type publication or list, and is null when it was temporarily unavailable. recommendations is still served in that case.
Substack Recommendations API FAQ
What is the difference between recommendations and top?
recommendations is the set the publication recommends. top is Substack's ordered list, which can include list rows as well as publications.
Why is top null?
When the ordered list is temporarily unavailable, top is null and recommendations is still returned rather than failing the whole request.
How many recommendations can I request?
Between 1 and 99, with 50 as the default.
How many credits does a recommendations lookup 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
- Publication feedGET /v1/substack/publications/{publication}/feed
- PostGET /v1/substack/posts/{post}
- CommentsGET /v1/substack/posts/{post}/comments