# Social Fetch API - Substack endpoints
# Base URL: https://api.socialfetch.dev
# Auth: x-api-key header (sfk_...)
# Full catalog: https://www.socialfetch.dev/llms-endpoints.txt | JSON: https://www.socialfetch.dev/llms.json
# Docs hub: https://www.socialfetch.dev/docs/api | OpenAPI: https://www.socialfetch.dev/openapi.json

26 documented Substack operations. Do not invent paths - only the routes below (and their linked markdown pages) are supported.

## GET /v1/substack/publications/{publication}
Get Substack publication
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/substack/publications/publication/get.mdx
SDK: client.substack.getPublication({ publication: "astralcodexten" })
Parameters:
- publication (required, string) - 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.
Outcome field: `data.lookupStatus` in `found`, `not_found`, `restricted`
curl "https://api.socialfetch.dev/v1/substack/publications/astralcodexten" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/substack/publications/{publication}/posts
List Substack publication posts
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/substack/publications/publication/posts/get.mdx
SDK: client.substack.listPublicationPosts({ publication: "astralcodexten" })
Parameters:
- publication (required, string) - 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.
- sort (optional, string, enum: new | top | pinned) - Order. `oldest` is not supported.
- query (optional, string) - Only posts whose text matches this string.
- section (optional, integer) - Only posts in this section id (from the publication's sections).
- page (optional, integer) - Page number, 0 to 100,000; leave it at 0 and follow `page.nextCursor`. A page above 0 is refused with a 400 because the archive pages by cursor.
- cursor (optional, string) - Opaque cursor from the previous page's `page.nextCursor`. Omit it for the first page.
- limit (optional, integer) - Rows to return, 1 to 23.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Outcome field: `data.lookupStatus` in `found`, `not_found`, `restricted`
curl "https://api.socialfetch.dev/v1/substack/publications/astralcodexten/posts" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/substack/publications/{publication}/posts/bodies
List Substack posts with bodies
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/substack/publications/publication/posts/bodies/get.mdx
SDK: client.substack.listPublicationPostBodies({ publication: "astralcodexten", limit: 10 })
Parameters:
- publication (required, string) - 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.
- limit (optional, integer) - Posts to return, 1 to 50.
- cursor (optional, string) - Opaque cursor from the previous page's `nextCursor`.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Outcome field: `data.lookupStatus` in `found`, `not_found`, `restricted`
curl "https://api.socialfetch.dev/v1/substack/publications/astralcodexten/posts/bodies?limit=10" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/substack/publications/{publication}/posts/index
List Substack publication post index
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/substack/publications/publication/posts/index/get.mdx
SDK: client.substack.listPublicationPostIndex({ publication: "astralcodexten" })
Parameters:
- publication (required, string) - 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.
Outcome field: `data.lookupStatus` in `found`, `not_found`, `restricted`
curl "https://api.socialfetch.dev/v1/substack/publications/astralcodexten/posts/index" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/substack/publications/{publication}/posts/search
Search Substack publication posts
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/substack/publications/publication/posts/search/get.mdx
SDK: client.substack.searchPublicationPosts({ publication: "astralcodexten", query: "climate" })
Parameters:
- publication (required, string) - 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.
- query (required, string) - Text to search for inside the publication.
- page (optional, integer) - Page number, 0 to 20; ten results a page.
Pagination: send query `page` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Outcome field: `data.lookupStatus` in `found`, `not_found`, `restricted`
curl "https://api.socialfetch.dev/v1/substack/publications/astralcodexten/posts/search?query=climate" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/substack/publications/{publication}/recommendations
List Substack recommended publications
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/substack/publications/publication/recommendations/get.mdx
SDK: client.substack.listPublicationRecommendations({ publication: "astralcodexten", limit: 5 })
Parameters:
- publication (required, string) - 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.
- limit (optional, integer) - Recommendations to return, 1 to 99.
Outcome field: `data.lookupStatus` in `found`, `not_found`, `restricted`
curl "https://api.socialfetch.dev/v1/substack/publications/astralcodexten/recommendations?limit=5" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/substack/publications/{publication}/feed
Get Substack publication feed
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/substack/publications/publication/feed/get.mdx
SDK: client.substack.getPublicationFeed({ publication: "astralcodexten" })
Parameters:
- publication (required, string) - 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.
Outcome field: `data.lookupStatus` in `found`, `not_found`, `restricted`
curl "https://api.socialfetch.dev/v1/substack/publications/astralcodexten/feed" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/substack/posts/{post}
Get Substack post
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/substack/posts/post/get.mdx
SDK: client.substack.getPost({ post: "223208969" })
Parameters:
- post (required, string) - A post: its numeric id (`223208969`) or its URL (`https://www.astralcodexten.com/p/...`). Post comments need the URL form.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/substack/posts/223208969" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/substack/posts/{post}/comments
List Substack post comments
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/substack/posts/post/comments/get.mdx
SDK: client.substack.listPostComments({ post: "https://www.astralcodexten.com/p/open-thread-400" })
Parameters:
- post (required, string) - A post: its numeric id (`223208969`) or its URL (`https://www.astralcodexten.com/p/...`). Post comments need the URL form.
- sort (optional, string, enum: best | oldest | newest) - Comment order. The whole tree is returned either way.
Outcome field: `data.lookupStatus` in `found`, `not_found`, `restricted`
curl "https://api.socialfetch.dev/v1/substack/posts/https%3A%2F%2Fwww.astralcodexten.com%2Fp%2Fopen-thread-400/comments" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/substack/posts/{post}/reactors
List Substack post reactors
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/substack/posts/post/reactors/get.mdx
SDK: client.substack.listPostReactors({ post: "223208969" })
Parameters:
- post (required, string) - A post: its numeric id (`223208969`) or its URL (`https://www.astralcodexten.com/p/...`). Post comments need the URL form.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/substack/posts/223208969/reactors" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/substack/posts/{post}/restackers
List Substack post restackers
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/substack/posts/post/restackers/get.mdx
SDK: client.substack.listPostRestackers({ post: "223208969" })
Parameters:
- post (required, string) - A post: its numeric id (`223208969`) or its URL (`https://www.astralcodexten.com/p/...`). Post comments need the URL form.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/substack/posts/223208969/restackers" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/substack/profiles/{handle}
Get Substack profile
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/substack/profiles/handle/get.mdx
SDK: client.substack.getProfile({ handle: "dieworkwear" })
Parameters:
- handle (required, string) - A profile handle, e.g. `dieworkwear` or `@dieworkwear`.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/substack/profiles/dieworkwear" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/substack/profiles/{handle}/posts
List Substack profile posts
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/substack/profiles/handle/posts/get.mdx
SDK: client.substack.listProfilePosts({ handle: "dieworkwear", limit: 5 })
Parameters:
- handle (required, string) - A profile handle, e.g. `dieworkwear` or `@dieworkwear`.
- limit (optional, integer) - Posts to return, 1 to 50. No further posts are available past this limit, so use 50 to get all that are available.
- cursor (optional, string) - Opaque cursor from the previous page's `nextCursor`.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/substack/profiles/dieworkwear/posts?limit=5" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/substack/profiles/{handle}/notes
List Substack profile notes
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/substack/profiles/handle/notes/get.mdx
SDK: client.substack.listProfileNotes({ handle: "dieworkwear", type: "notes" })
Parameters:
- handle (required, string) - A profile handle, e.g. `dieworkwear` or `@dieworkwear`.
- type (optional, string, enum: notes | replies | all) - `notes` for the person's own notes, `replies` for their replies, `all` for both.
- cursor (optional, string) - Opaque cursor from the previous page's `nextCursor`.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/substack/profiles/dieworkwear/notes?type=notes" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/substack/profiles/{handle}/subscriptions
List Substack profile subscriptions
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/substack/profiles/handle/subscriptions/get.mdx
SDK: client.substack.listProfileSubscriptions({ handle: "dieworkwear" })
Parameters:
- handle (required, string) - A profile handle, e.g. `dieworkwear` or `@dieworkwear`.
- cursor (optional, string) - Opaque cursor from the previous page's `nextCursor`.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/substack/profiles/dieworkwear/subscriptions" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/substack/notes/{noteId}
Get Substack note
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/substack/notes/noteid/get.mdx
SDK: client.substack.getNote({ noteId: "378007586" })
Parameters:
- noteId (required, string) - A note id as Substack displays it, e.g. `378007586`.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/substack/notes/378007586" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/substack/notes/{noteId}/replies
List Substack note replies
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/substack/notes/noteid/replies/get.mdx
SDK: client.substack.listNoteReplies({ noteId: "378007586" })
Parameters:
- noteId (required, string) - A note id as Substack displays it, e.g. `378007586`.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/substack/notes/378007586/replies" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/substack/notes/{noteId}/restacks
List Substack note restacks
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/substack/notes/noteid/restacks/get.mdx
SDK: client.substack.listNoteRestacks({ noteId: "378007586" })
Parameters:
- noteId (required, string) - A note id as Substack displays it, e.g. `378007586`.
- cursor (optional, string) - Opaque cursor from the previous page's `nextCursor`.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/substack/notes/378007586/restacks" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/substack/search/profiles
Search Substack profiles
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/substack/search/profiles/get.mdx
SDK: client.substack.searchProfiles({ query: "climate" })
Parameters:
- query (required, string) - Text to search profiles for.
- page (optional, integer) - Page number, 0 to 100,000; twenty profiles a page. Only pages 0 to 3 have results, so a page past 3 returns an empty list with `hasMore: false`.
Pagination: send query `page` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/substack/search/profiles?query=climate" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/substack/search
Search Substack posts, notes and people
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/substack/search/get.mdx
SDK: client.substack.searchTop({ query: "climate" })
Parameters:
- query (required, string) - Text to search posts, notes and profiles for.
- cursor (optional, string) - Opaque cursor from the previous page's `nextCursor`.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/substack/search?query=climate" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/substack/search/publications
Search Substack publications
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/substack/search/publications/get.mdx
SDK: client.substack.searchPublications({ query: "climate" })
Parameters:
- query (required, string) - Text to search publications for.
- page (optional, integer) - Page number, 0 to 100,000; twenty publications a page. Only pages 0 to 3 have results, so a page past 3 returns an empty list with `hasMore: false`.
Pagination: send query `page` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/substack/search/publications?query=climate" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/substack/search/podcasts
Search Substack podcast shows
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/substack/search/podcasts/get.mdx
SDK: client.substack.searchPodcasts({ query: "climate" })
Parameters:
- query (required, string) - Text to search podcast shows for.
- cursor (optional, string) - Opaque cursor from the previous page's `nextCursor`.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/substack/search/podcasts?query=climate" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/substack/categories
List Substack categories
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/substack/categories/get.mdx
SDK: client.substack.listCategories()
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/substack/categories" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/substack/categories/{categoryId}/publications
List Substack category leaderboard
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/substack/categories/categoryid/publications/get.mdx
SDK: client.substack.listCategoryPublications({ categoryId: 4, ranking: "all" })
Parameters:
- categoryId (required, integer) - A numeric category id from `GET /v1/substack/categories`.
- ranking (optional, string, enum: all | paid | trending) - Which leaderboard to return.
- page (optional, integer) - Page number, 0 to 100,000; twenty-five publications a page. Only pages 0 to 20 have results, so a page past 20 returns an empty list with `hasMore: false`.
Pagination: send query `page` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/substack/categories/4/publications?ranking=all" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/substack/notes/explore
List Substack explore feed
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/substack/notes/explore/get.mdx
SDK: client.substack.listExploreNotes()
Parameters:
- cursor (optional, string) - Opaque cursor from the previous page's `nextCursor`.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/substack/notes/explore" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/substack/directory
List Substack publication directory
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/substack/directory/get.mdx
SDK: client.substack.listDirectory({ file: 1, limit: 5 })
Parameters:
- file (optional, integer) - Directory file, 1 to 24. Each file is a numbered slice of the directory, not a category.
- page (optional, integer) - Page number form, 0 to 100,000; `limit` entries a page. Prefer `cursor` for the next page.
- cursor (optional, string) - The way to page: pass `page.nextCursor` from the previous response to get the next page. A directory cursor belongs to the file that issued it.
- limit (optional, integer) - Entries to return, 1 to 5,000.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/substack/directory?file=1&limit=5" \
  -H "x-api-key: YOUR_API_KEY"