List Substack recommended publications List the publications a Substack publication recommends.
GET /v1/substack/publications/{publication}/recommendations
x-api-key* string header
API key (`sfk_...`)
publication* string required path
A publication: its numeric id (`89120`), its Substack subdomain (`astralcodexten`), its host (`www.astralcodexten.com`) or its URL. A numeric id is refused with a 400 on the routes that need a subdomain, host or URL.
min 1 chars · max 400 chars
limit integer optional query
Recommendations to return, 1 to 99.
≥ 1 · ≤ 99
Response fields 259 Expand all Collapse all Collapse all Endpoint-specific response payload.
Whether the publication was found.
one of: found, not_found, restricted
data . restrictedReason
string nullable
Why the publication is restricted, when it is.
one of: invite_only, flagged, paid, null
data . publicationId
integer nullable
Numeric publication id.
Publications the publication recommends.
data . recommendations [] . id
integer nullable
Numeric recommendation id.
data . recommendations [] . recommendedPublicationId
integer nullable
The recommended publication's id.
data . recommendations [] . recommendingPublicationId
integer nullable
The recommending publication's id.
data . recommendations [] . createdAt
string nullable
ISO 8601 timestamp, or null when Substack does not publish one.
data . recommendations [] . blurb
string nullable
The recommendation's blurb.
data . recommendations [] . publication object nullable
The recommended publication.
data . recommendations [] . publication . id
integer
Numeric publication id.
data . recommendations [] . publication . name
string nullable
The publication's name.
data . recommendations [] . publication . subdomain
string nullable
The publication's Substack subdomain.
data . recommendations [] . publication . customDomain
string nullable
The publication's custom domain, when it has one.
data . recommendations [] . publication . apexDomain
string nullable
The publication's apex domain, when it has one.
data . recommendations [] . publication . url
string nullable
The publication's canonical base URL.
data . recommendations [] . publication . host
string nullable
The host its pages are served from.
data . recommendations [] . publication . description
string nullable
The publication's description.
data . recommendations [] . publication . language
string nullable
The publication's language code.
data . recommendations [] . publication . kind
string nullable
`newsletter`, `podcast` or Substack's own type.
data . recommendations [] . publication . createdAt
string nullable
ISO 8601 timestamp, or null when Substack does not publish one.
data . recommendations [] . publication . firstPostAt
string nullable
ISO 8601 timestamp, or null when Substack does not publish one.
data . recommendations [] . publication . hasPosts
boolean nullable
Whether the publication has posts.
data . recommendations [] . publication . isExplicit
boolean nullable
Whether the publication is marked explicit.
data . recommendations [] . publication . isInviteOnly
boolean nullable
Whether the publication is invite-only.
data . recommendations [] . publication . isFlagged
boolean nullable
Whether the publication is flagged.
data . recommendations [] . publication . noIndex
boolean nullable
Whether search engines are asked not to index it.
data . recommendations [] . publication . isOnSubstack
boolean nullable
Whether the publication is hosted by Substack.
data . recommendations [] . publication . commentsEnabled
boolean nullable
Whether comments are enabled.
data . recommendations [] . publication . notesEnabled
boolean nullable
Whether Notes are enabled.
data . recommendations [] . publication . defaultCommentSort
string nullable
The default comment order.
data . recommendations [] . publication . annualDisabled
boolean nullable
Whether annual plans are disabled.
data . recommendations [] . publication . monthlyDisabled
boolean nullable
Whether monthly plans are disabled.
data . recommendations [] . publication . paymentsState
string nullable
The publication's payments state.
data . recommendations [] . publication . freeTrialEnabled
boolean nullable
Whether a free trial is offered.
data . recommendations [] . publication . pausedUntil
string nullable
ISO 8601 timestamp, or null when Substack does not publish one.
data . recommendations [] . publication . emailBannerUrl
string nullable
The email banner image URL.
data . recommendations [] . publication . copyright
string nullable
The copyright line the publication prints.
data . recommendations [] . publication . logoUrl
string nullable
The publication's logo URL.
data . recommendations [] . publication . wideLogoUrl
string nullable
The publication's wide logo URL.
data . recommendations [] . publication . coverImageUrl
string nullable
The publication's cover image URL.
data . recommendations [] . publication . foundingPlanName
string nullable
The name of the founding-member plan.
data . recommendations [] . publication . hasRecommendations
boolean nullable
Whether the publication recommends others.
data . recommendations [] . publication . benefits object
The benefit lists for each subscription tier.
data . recommendations [] . publication . benefits . free array
Benefits for free subscribers.
data . recommendations [] . publication . benefits . free []
string optional
data . recommendations [] . publication . benefits . paid array
Benefits for paid subscribers.
data . recommendations [] . publication . benefits . paid []
string optional
data . recommendations [] . publication . benefits . founding array
Benefits for founding members.
data . recommendations [] . publication . benefits . founding []
string optional
data . recommendations [] . publication . author object
The publication's main author.
data . recommendations [] . publication . author . id
integer nullable
Numeric user id.
data . recommendations [] . publication . author . name
string nullable
The name shown for the author.
data . recommendations [] . publication . author . handle
string nullable
The author's handle.
data . recommendations [] . publication . author . slug
string nullable
The author's profile slug.
data . recommendations [] . publication . author . bio
string nullable
The author's short biography.
data . recommendations [] . publication . author . photoUrl
string nullable
The author's profile photo URL.
data . recommendations [] . publication . author . badge object nullable
The author's main badge, when there is one.
data . recommendations [] . publication . author . badge . type
string nullable
The kind of badge, such as `bestseller`.
data . recommendations [] . publication . author . badge . tier
integer nullable
The badge tier, when it has one.
data . recommendations [] . publication . author . badge . handle
string nullable
The handle the badge belongs to.
data . recommendations [] . publication . author . badge . service
string nullable
The service the badge comes from.
data . recommendations [] . publication . author . badge . url
string nullable
A link for the badge, when it has one.
data . recommendations [] . publication . author . badges
object nullable
The author's reader status fields, when available.
data . recommendations [] . publication . author . bestsellerTier
integer nullable
The author's bestseller tier.
data . recommendations [] . publication . author . primaryPublication object nullable
The author's primary publication, when there is one.
data . recommendations [] . publication . author . primaryPublication . id
integer nullable
Numeric publication id.
data . recommendations [] . publication . author . primaryPublication . name
string nullable
The publication's name.
data . recommendations [] . publication . author . primaryPublication . subdomain
string nullable
The publication's Substack subdomain.
data . recommendations [] . publication . author . primaryPublication . customDomain
string nullable
The publication's custom domain, when it has one.
data . recommendations [] . publication . author . primaryPublication . logoUrl
string nullable
The publication's logo URL.
data . recommendations [] . publication . audience object
Approximate audience figures the publication prints. These are bands, not counts.
data . recommendations [] . publication . audience . paidLabel
string nullable
The band Substack displays for paid subscribers.
data . recommendations [] . publication . audience . paidOrderOfMagnitude
integer nullable
The order of magnitude behind the paid band.
data . recommendations [] . publication . audience . totalLabel
string nullable
The band Substack displays for all subscribers.
data . recommendations [] . publication . audience . totalOrderOfMagnitude
integer nullable
The order of magnitude behind the total band.
data . recommendations [] . publication . audience . freeLabel
string nullable
The band Substack displays for free subscribers.
data . recommendations [] . publication . audience . freeShort
string nullable
The short free-subscriber band.
data . recommendations [] . publication . audience . chatMembersLabel
string nullable
The band Substack displays for chat members.
data . recommendations [] . publication . contributors array
People with a byline on the publication.
data . recommendations [] . publication . contributors [] . id
integer nullable
Numeric user id.
data . recommendations [] . publication . contributors [] . name
string nullable
The contributor's name.
data . recommendations [] . publication . contributors [] . handle
string nullable
The contributor's handle.
data . recommendations [] . publication . contributors [] . role
string nullable
The contributor's role on the publication.
data . recommendations [] . publication . contributors [] . owner
boolean nullable
Whether the contributor owns the publication.
data . recommendations [] . publication . contributors [] . photoUrl
string nullable
The contributor's photo URL.
data . recommendations [] . publication . contributors [] . bio
string nullable
The contributor's short biography.
data . recommendations [] . publication . contributors [] . badge object nullable
The contributor's badge.
data . recommendations [] . publication . contributors [] . badge . type
string nullable
The kind of badge, such as `bestseller`.
data . recommendations [] . publication . contributors [] . badge . tier
integer nullable
The badge tier, when it has one.
data . recommendations [] . publication . contributors [] . badge . handle
string nullable
The handle the badge belongs to.
data . recommendations [] . publication . contributors [] . badge . service
string nullable
The service the badge comes from.
data . recommendations [] . publication . contributors [] . badge . url
string nullable
A link for the badge, when it has one.
data . recommendations [] . publication . contributors [] . bestsellerTier
integer nullable
The contributor's bestseller tier.
data . recommendations [] . publication . sections array
The publication's sections.
data . recommendations [] . publication . sections [] . id
integer nullable
Numeric section id.
data . recommendations [] . publication . sections [] . name
string nullable
The section's name.
data . recommendations [] . publication . sections [] . description
string nullable
The section's description.
data . recommendations [] . publication . sections [] . slug
string nullable
The section's URL slug.
data . recommendations [] . publication . sections [] . isPodcast
boolean nullable
Whether the section is a podcast.
data . recommendations [] . publication . sections [] . isLive
boolean nullable
Whether the section is a live stream.
data . recommendations [] . publication . sections [] . isDefaultOn
boolean nullable
Whether the section is on by default.
data . recommendations [] . publication . sections [] . logoUrl
string nullable
The section's logo URL.
data . recommendations [] . publication . sections [] . coverImageUrl
string nullable
The section's cover image URL.
data . recommendations [] . publication . sections [] . hideFromNavbar
boolean nullable
Whether the section is hidden from navigation.
data . recommendations [] . publication . sections [] . hidePostsFromPubListings
boolean nullable
Whether the section's posts are hidden from publication lists.
data . recommendations [] . publication . links array
Links the publication shows.
data . recommendations [] . publication . links [] . id
integer nullable
Numeric link id.
data . recommendations [] . publication . links [] . url
string
The link.
data . recommendations [] . publication . links [] . platform
string nullable
`apple_podcasts`, `spotify`, `youtube` or another label Substack uses.
data . recommendations [] . publication . links [] . sectionId
integer nullable
The section the link belongs to, when it has one.
data . recommendations [] . publication . plans array
The subscription plans the publication offers.
data . recommendations [] . publication . plans [] . id
string nullable
The plan's id.
data . recommendations [] . publication . plans [] . nickname
string nullable
The plan's display name.
data . recommendations [] . publication . plans [] . amount
integer nullable
Price in the currency's minor unit.
data . recommendations [] . publication . plans [] . currency
string nullable
Currency code for the price.
data . recommendations [] . publication . plans [] . interval
string nullable
`month`, `year` or Substack's own value.
data . recommendations [] . publication . plans [] . intervalCount
integer nullable
How many intervals one charge covers.
data . recommendations [] . publication . plans [] . active
boolean nullable
Whether the plan is on sale.
data . recommendations [] . publication . plans [] . founding
boolean
Whether this is a founding-member plan.
data . recommendations [] . publication . podcast object
The publication's podcast, when it has one.
data . recommendations [] . publication . podcast . exists
boolean nullable
Whether the publication has a podcast.
data . recommendations [] . publication . podcast . hasFreeEpisodes
boolean nullable
Whether free episodes are available.
data . recommendations [] . publication . podcast . hasPaidEpisodes
boolean nullable
Whether paid episodes are available.
data . recommendations [] . publication . podcast . artUrl
string nullable
The podcast artwork URL.
data . recommendations [] . publication . podcast . byline
string nullable
The podcast byline.
data . recommendations [] . publication . podcast . description
string nullable
The podcast description.
data . recommendations [] . publication . podcast . feedUrl
string nullable
The podcast feed URL.
data . recommendations [] . publication . podcast . title
string nullable
The podcast title.
data . recommendations [] . publication . podcast . paidEpisodeArtUrl
string nullable
Artwork for paid episodes.
Substack's ordered recommendation list; null when it was temporarily unavailable.
Whether the row is a publication or a list.
one of: publication, list
The publication, when the row is a publication.
data . top [] . publication . id
integer
Numeric publication id.
data . top [] . publication . name
string nullable
The publication's name.
data . top [] . publication . subdomain
string nullable
The publication's Substack subdomain.
data . top [] . publication . customDomain
string nullable
The publication's custom domain, when it has one.
data . top [] . publication . apexDomain
string nullable
The publication's apex domain, when it has one.
data . top [] . publication . url
string nullable
The publication's canonical base URL.
data . top [] . publication . host
string nullable
The host its pages are served from.
data . top [] . publication . description
string nullable
The publication's description.
data . top [] . publication . language
string nullable
The publication's language code.
data . top [] . publication . kind
string nullable
`newsletter`, `podcast` or Substack's own type.
data . top [] . publication . createdAt
string nullable
ISO 8601 timestamp, or null when Substack does not publish one.
data . top [] . publication . firstPostAt
string nullable
ISO 8601 timestamp, or null when Substack does not publish one.
data . top [] . publication . hasPosts
boolean nullable
Whether the publication has posts.
data . top [] . publication . isExplicit
boolean nullable
Whether the publication is marked explicit.
data . top [] . publication . isInviteOnly
boolean nullable
Whether the publication is invite-only.
data . top [] . publication . isFlagged
boolean nullable
Whether the publication is flagged.
data . top [] . publication . noIndex
boolean nullable
Whether search engines are asked not to index it.
data . top [] . publication . isOnSubstack
boolean nullable
Whether the publication is hosted by Substack.
data . top [] . publication . commentsEnabled
boolean nullable
Whether comments are enabled.
data . top [] . publication . notesEnabled
boolean nullable
Whether Notes are enabled.
data . top [] . publication . defaultCommentSort
string nullable
The default comment order.
data . top [] . publication . annualDisabled
boolean nullable
Whether annual plans are disabled.
data . top [] . publication . monthlyDisabled
boolean nullable
Whether monthly plans are disabled.
data . top [] . publication . paymentsState
string nullable
The publication's payments state.
data . top [] . publication . freeTrialEnabled
boolean nullable
Whether a free trial is offered.
data . top [] . publication . pausedUntil
string nullable
ISO 8601 timestamp, or null when Substack does not publish one.
data . top [] . publication . emailBannerUrl
string nullable
The email banner image URL.
data . top [] . publication . copyright
string nullable
The copyright line the publication prints.
data . top [] . publication . logoUrl
string nullable
The publication's logo URL.
data . top [] . publication . wideLogoUrl
string nullable
The publication's wide logo URL.
data . top [] . publication . coverImageUrl
string nullable
The publication's cover image URL.
data . top [] . publication . foundingPlanName
string nullable
The name of the founding-member plan.
data . top [] . publication . hasRecommendations
boolean nullable
Whether the publication recommends others.
data . top [] . publication . benefits object
The benefit lists for each subscription tier.
data . top [] . publication . benefits . free array
Benefits for free subscribers.
data . top [] . publication . benefits . free []
string optional
data . top [] . publication . benefits . paid array
Benefits for paid subscribers.
data . top [] . publication . benefits . paid []
string optional
data . top [] . publication . benefits . founding array
Benefits for founding members.
data . top [] . publication . benefits . founding []
string optional
data . top [] . publication . author object
The publication's main author.
data . top [] . publication . author . id
integer nullable
Numeric user id.
data . top [] . publication . author . name
string nullable
The name shown for the author.
data . top [] . publication . author . handle
string nullable
The author's handle.
data . top [] . publication . author . slug
string nullable
The author's profile slug.
data . top [] . publication . author . bio
string nullable
The author's short biography.
data . top [] . publication . author . photoUrl
string nullable
The author's profile photo URL.
data . top [] . publication . author . badge object nullable
The author's main badge, when there is one.
data . top [] . publication . author . badge . type
string nullable
The kind of badge, such as `bestseller`.
data . top [] . publication . author . badge . tier
integer nullable
The badge tier, when it has one.
data . top [] . publication . author . badge . handle
string nullable
The handle the badge belongs to.
data . top [] . publication . author . badge . service
string nullable
The service the badge comes from.
data . top [] . publication . author . badge . url
string nullable
A link for the badge, when it has one.
data . top [] . publication . author . badges
object nullable
The author's reader status fields, when available.
data . top [] . publication . author . bestsellerTier
integer nullable
The author's bestseller tier.
data . top [] . publication . author . primaryPublication object nullable
The author's primary publication, when there is one.
data . top [] . publication . author . primaryPublication . id
integer nullable
Numeric publication id.
data . top [] . publication . author . primaryPublication . name
string nullable
The publication's name.
data . top [] . publication . author . primaryPublication . subdomain
string nullable
The publication's Substack subdomain.
data . top [] . publication . author . primaryPublication . customDomain
string nullable
The publication's custom domain, when it has one.
data . top [] . publication . author . primaryPublication . logoUrl
string nullable
The publication's logo URL.
data . top [] . publication . audience object
Approximate audience figures the publication prints. These are bands, not counts.
data . top [] . publication . audience . paidLabel
string nullable
The band Substack displays for paid subscribers.
data . top [] . publication . audience . paidOrderOfMagnitude
integer nullable
The order of magnitude behind the paid band.
data . top [] . publication . audience . totalLabel
string nullable
The band Substack displays for all subscribers.
data . top [] . publication . audience . totalOrderOfMagnitude
integer nullable
The order of magnitude behind the total band.
data . top [] . publication . audience . freeLabel
string nullable
The band Substack displays for free subscribers.
data . top [] . publication . audience . freeShort
string nullable
The short free-subscriber band.
data . top [] . publication . audience . chatMembersLabel
string nullable
The band Substack displays for chat members.
data . top [] . publication . contributors array
People with a byline on the publication.
data . top [] . publication . contributors [] . id
integer nullable
Numeric user id.
data . top [] . publication . contributors [] . name
string nullable
The contributor's name.
data . top [] . publication . contributors [] . handle
string nullable
The contributor's handle.
data . top [] . publication . contributors [] . role
string nullable
The contributor's role on the publication.
data . top [] . publication . contributors [] . owner
boolean nullable
Whether the contributor owns the publication.
data . top [] . publication . contributors [] . photoUrl
string nullable
The contributor's photo URL.
data . top [] . publication . contributors [] . bio
string nullable
The contributor's short biography.
data . top [] . publication . contributors [] . badge object nullable
The contributor's badge.
data . top [] . publication . contributors [] . badge . type
string nullable
The kind of badge, such as `bestseller`.
data . top [] . publication . contributors [] . badge . tier
integer nullable
The badge tier, when it has one.
data . top [] . publication . contributors [] . badge . handle
string nullable
The handle the badge belongs to.
data . top [] . publication . contributors [] . badge . service
string nullable
The service the badge comes from.
data . top [] . publication . contributors [] . badge . url
string nullable
A link for the badge, when it has one.
data . top [] . publication . contributors [] . bestsellerTier
integer nullable
The contributor's bestseller tier.
data . top [] . publication . sections array
The publication's sections.
data . top [] . publication . sections [] . id
integer nullable
Numeric section id.
data . top [] . publication . sections [] . name
string nullable
The section's name.
data . top [] . publication . sections [] . description
string nullable
The section's description.
data . top [] . publication . sections [] . slug
string nullable
The section's URL slug.
data . top [] . publication . sections [] . isPodcast
boolean nullable
Whether the section is a podcast.
data . top [] . publication . sections [] . isLive
boolean nullable
Whether the section is a live stream.
data . top [] . publication . sections [] . isDefaultOn
boolean nullable
Whether the section is on by default.
data . top [] . publication . sections [] . logoUrl
string nullable
The section's logo URL.
data . top [] . publication . sections [] . coverImageUrl
string nullable
The section's cover image URL.
data . top [] . publication . sections [] . hideFromNavbar
boolean nullable
Whether the section is hidden from navigation.
data . top [] . publication . sections [] . hidePostsFromPubListings
boolean nullable
Whether the section's posts are hidden from publication lists.
data . top [] . publication . links array
Links the publication shows.
data . top [] . publication . links [] . id
integer nullable
Numeric link id.
data . top [] . publication . links [] . url
string
The link.
data . top [] . publication . links [] . platform
string nullable
`apple_podcasts`, `spotify`, `youtube` or another label Substack uses.
data . top [] . publication . links [] . sectionId
integer nullable
The section the link belongs to, when it has one.
data . top [] . publication . plans array
The subscription plans the publication offers.
data . top [] . publication . plans [] . id
string nullable
The plan's id.
data . top [] . publication . plans [] . nickname
string nullable
The plan's display name.
data . top [] . publication . plans [] . amount
integer nullable
Price in the currency's minor unit.
data . top [] . publication . plans [] . currency
string nullable
Currency code for the price.
data . top [] . publication . plans [] . interval
string nullable
`month`, `year` or Substack's own value.
data . top [] . publication . plans [] . intervalCount
integer nullable
How many intervals one charge covers.
data . top [] . publication . plans [] . active
boolean nullable
Whether the plan is on sale.
data . top [] . publication . plans [] . founding
boolean
Whether this is a founding-member plan.
data . top [] . publication . podcast object
The publication's podcast, when it has one.
data . top [] . publication . podcast . exists
boolean nullable
Whether the publication has a podcast.
data . top [] . publication . podcast . hasFreeEpisodes
boolean nullable
Whether free episodes are available.
data . top [] . publication . podcast . hasPaidEpisodes
boolean nullable
Whether paid episodes are available.
data . top [] . publication . podcast . artUrl
string nullable
The podcast artwork URL.
data . top [] . publication . podcast . byline
string nullable
The podcast byline.
data . top [] . publication . podcast . description
string nullable
The podcast description.
data . top [] . publication . podcast . feedUrl
string nullable
The podcast feed URL.
data . top [] . publication . podcast . title
string nullable
The podcast title.
data . top [] . publication . podcast . paidEpisodeArtUrl
string nullable
Artwork for paid episodes.
data . top [] . list
object nullable
The list, when the row is a list.
Metadata describing the request and billing outcome.
Unique request identifier for tracing this API call.
meta . creditsCharged
integer
Credits charged for this request.
Public API version that served the response.