Substack API

Newsletter, subscriber and post data as JSON

Substack doesn't offer a public API for newsletter, subscriber or post data. The Subalytics Substack API does: weekly creator snapshots, subscriber history and posts, over HTTPS with an API key.

featured in

Vogue Digiday Elle Yahoo US Chamber of Commerce Co Magazine Vanity Fair

Substack does not publish a public API for newsletter, post or subscriber data. Subalytics tracks Substack newsletters every week and makes that data available through a read-only JSON API.

Use it to list newsletters with their subscriber counts, follow a newsletter's free and paid subscriber history week by week, and search posts by audience, length and engagement. Every endpoint uses GET, filters with query parameters and returns the same response envelope.

Newsletters are identified by a stable Subalytics ID (sub_id), the same ID used across the creator endpoints, so you can join snapshots, history and posts.

Endpoints for Substack data

Each endpoint links to its full reference in the API documentation.

Influencers

/api/v1/influencers/?social=substack

The latest weekly snapshot of each Substack creator: subscriber counts, publication details and more. Filter by Subalytics ID, year and minimum free or paid subscribers. Cursor pagination.

Creators (historical)

/api/v1/creators-historical/?social=substack

Weekly creator records by Subalytics ID, platform, week and year, or a date range. Offset pagination.

Subscribers (historical)

/api/v1/subscribers-historical/?social=substack

Weekly subscriber statistics by Subalytics ID, platform and date, with minimum free and paid subscriber filters. Offset pagination.

Substack posts

/api/v1/substack-posts/

Search posts by creator, audience and engagement. Returns post summaries by default (title, URL, date, description, a truncated body and engagement counts); full=true returns the complete post record. Cursor pagination.

Substack posts with company mentions

/api/v1/entity-substack-posts/

Substack posts that mention at least one monitored public company, each with the mentions found. Part of the separate Entity Mentions product, with its own access.

Example requests

Base URL: https://subalytics.com/api/v1/. Send your API key in the X-API-key header; every request is a GET with query parameters.

curl -H "X-API-key: <your-api-key>" \
  "https://subalytics.com/api/v1/influencers/?social=substack&free_subscribers=5000"

GET /api/v1/creators-historical/?sub_id=714165582b&year=2025&limit=20
GET /api/v1/subscribers-historical/?sub_id=f2ac9f1545&from=2025-03-01&to=2025-05-01&limit=50
GET /api/v1/substack-posts/?sub_id=803b198749&audience=only_paid

Weekly creator snapshot: query parameters

The influencers endpoint returns the latest weekly snapshot of each creator. Use social=substack to limit it to Substack.

ParameterTypeDescription
sub_idstringSubalytics ID of one creator
socialstringPlatform: substack, medium or bluesky
yearintYear of the snapshot
free_subscribersintMinimum number of free subscribers
paid_subscribersintMinimum number of paid subscribers
limitintResults per page (default 25, max 100)
cursorstringnext_cursor from the previous page

Subscriber history: query parameters

The subscribers (historical) endpoint returns one record per creator per week. from and to apply to the start date of each weekly record; dates are UTC, YYYY-MM-DD.

ParameterTypeDescription
sub_idstringSubalytics ID of one creator
socialstringPlatform: substack, medium or bluesky
week_numberintISO week number (1–53)
yearintYear, e.g. 2025
free_subscribersintMinimum number of free subscribers
paid_subscribersintMinimum number of paid subscribers
fromstringStart date of the week, from (YYYY-MM-DD)
tostringStart date of the week, to (YYYY-MM-DD)
limitintResults per page (default 25, max 100)
offsetintRecords to skip (default 0)

Posts: query parameters

The Substack posts endpoint searches posts by creator, audience and engagement. By default it returns post summaries: title, URL, date, description, a truncated body and engagement counts. Add full=true for the complete post record.

ParameterTypeDescription
sub_idstringSubalytics ID of one creator
audiencestringAudience, e.g. only_paid or everyone
wordcountintMinimum word count
comment_countintMinimum number of comments
reaction_countintMinimum number of reactions
fullstringtrue = return the complete post record
limitintResults per page (default 25, max 100)
cursorstringnext_cursor from the previous page
GET /api/v1/substack-posts/?sub_id=803b198749&audience=only_paid

Responses and errors

Every endpoint returns the same JSON envelope. Cursor-paginated endpoints include next_cursor: pass it back as cursor to get the next page, and stop when it is null. Cursors are opaque strings: don't parse or build them.

Offset-paginated endpoints return "offset" in place of "next_cursor". An empty results list is a success, not an error.

CodeMeaningWhen
400Bad requestUnknown query parameter, invalid date or date range, invalid limit or invalid cursor. The message says which.
401UnauthorizedMissing API key, or the key is not enabled for this endpoint.
500Server errorSomething went wrong on our side. Retry later.
{
  "success": true,
  "results": [ ... ],
  "returned_results": 25,
  "limit": 25,
  "next_cursor": "6a7d976dc8173839e225382f"
}

How to get started

01

Request access

Tell us which endpoints you need. Keys are enabled per endpoint.

02

Get your API key

Send it in the X-API-key header with every request.

03

Query and page through results

Filter with query parameters and follow next_cursor or offset until the last page.

Request Access →

FAQ

Common questions

Substack does not offer a public API for newsletter, post or subscriber data. The Subalytics Substack API provides that data as JSON: weekly creator snapshots, subscriber history and posts.

The influencers and subscribers (historical) endpoints filter by minimum free_subscribers and paid_subscribers, and subscriber history is recorded weekly per newsletter.

Yes. The Substack posts endpoint filters by creator (sub_id), audience (e.g. only_paid or everyone), minimum word count, comments and reactions. full=true returns the complete post record.

Send your API key in the X-API-key header with every request. Each key is enabled for specific endpoints; a request without a valid key, or to an endpoint your key isn't enabled for, returns 401.

Every endpoint accepts limit (default 25, maximum 100). Cursor-paginated endpoints return next_cursor: pass it back as cursor and stop when it is null. Offset-paginated endpoints take offset: increase it by limit until a page returns fewer than limit results.

JSON over HTTPS. All endpoints use GET, filter with query parameters and return the same response envelope: success, results, returned_results, limit, and next_cursor or offset. Endpoint paths end with a trailing slash.

Any query parameter not listed for an endpoint is rejected with 400 and a message naming it, e.g. "Unknown parameters: bad_param", so typos don't silently return the wrong data.

Yes. A machine-readable OpenAPI 3.1 description of every documented endpoint is at https://subalytics.com/openapi.json, for API clients, code generators and AI tools.

Contact us

Have a question or a custom use case?

Tell us what you're trying to monitor or search across, and we'll get back to you within a business day.

Get access to the Substack API

Tell us which data you need and we'll enable the matching endpoints on your API key. The full reference, with every parameter and response field, is in the API documentation.