POST

API health

24h health
Normal
  • Healthy / normal
  • Available
  • Limited
  • Mostly down
Normal

Last 24 hours

Last 30 days

Collect a Substack writer's Notes, the short posts kept apart from newsletters, with text, kind, likes and publish time for each. It lists one writer's Notes only, not a sitewide search, and may not reach the full history.

Send POST https://api.everyinfra.com/api/v1/social with platform set to substack and action set to notes. Price $1.39 per 1,000 requests ($0.001389 per call). Failed calls and empty results are not charged. Synchronous. For slow jobs add "mode": "async" to the body, take the job_id and poll.

Substack Notes lists the Notes one writer has posted on Substack, given their username. Notes are Substack's short posts, separate from newsletter articles; each row carries the note's full text, its kind, the like count, the publish time, and the author's handle and display name. It answers what a writer shares in short form, for editors and media analysts following the writers in a niche, publishers studying which short posts draw likes, and writers comparing their Notes with their peers'.

username takes the author handle, such as astralcodexten, with or without an @, or a substack.com/@ profile link. The rows are Notes only: newsletter articles come from the Substack Publication posts capability, which takes the publication's link, and a single article from Substack Post details. Check kind to see what type of entry each row is, and read a null like_count as not disclosed rather than zero.

AI prompt

#
Please help me write a data collection script with the EveryInfra Substack Notes endpoint (substack/notes).

How the endpoint works:
- Request: POST https://api.everyinfra.com/api/v1/social with the header Authorization: Bearer <API key>. Read the key from the EVERYINFRA_API_KEY environment variable and never hard-code it.
- In the request body, set platform to substack and action to notes, and put the parameters inside params.
- Required parameters:
  - username: Specifies the target creator handle for profile or notes, accepted as a plain handle (with optional @ prefix) or a full substack.com/@user link.
- Optional parameters:
  - limit: The most rows to return in this call, an integer from 1 to 200. The default applies when you leave it out, and a call can return fewer rows. Larger values return 422 before any charge. (default: 25)
- Returns a list of records. Main fields of each record: id, kind, text, author_username, author_name, like_count, posted_at, restacked_post, attachment_urls.
- Example request body:
{
  "platform": "substack",
  "action": "notes",
  "params": {
    "username": "astralcodexten"
  }
}
- Price: $1.39 per 1,000 requests; failed and empty results are not charged.
- For dozens or hundreds of targets, add "mode": "async" to the body: you get a job_id at once and poll GET https://api.everyinfra.com/api/v1/jobs/{job_id} for the result.
- On 422, fix the request using the suggested parameter names and allowed values in the error; on 429 or 503, wait for Retry-After and try again.

Before writing code, ask me which targets I need, how many, which fields, and what output format I want; then confirm the plan and the rough cost with me.

Request parameters

#
NameInTypeRequiredDefaultDescription
AuthorizationheaderstringYes-Bearer followed by your API key. Create it in the console; never put it in a URL or a code repository.
platformbodystringYessubstackPlatform identifier, fixed value.
actionbodystringYesnotesCapability identifier, fixed value.
usernamebody.paramsstringYes-Specifies the target creator handle for profile or notes, accepted as a plain handle (with optional @ prefix) or a full substack.com/@user link. The notes action fetches short creator updates rather than long-form publication posts.
limitbody.paramsinteger (1–200)No25The most rows to return in this call, an integer from 1 to 200. The default applies when you leave it out, and a call can return fewer rows. Larger values return 422 before any charge.

Code samples

#
bash
curl -X POST 'https://api.everyinfra.com/api/v1/social' \
  -H "Authorization: Bearer $EVERYINFRA_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "platform": "substack",
  "action": "notes",
  "params": {
    "username": "astralcodexten"
  }
}'

OpenAPI definition (JSON)Samples read the key from the EVERYINFRA_API_KEY environment variable; copied code never contains your key.

Response example

#
Captured September 26, 2026 at 08:56 (UTC) by calling this API with the parameters in the code sample above. results and count are that call's real response with personal information (names, handles, avatars, profile links, contact details) removed; the list keeps the first 2. id, billing and quota differ on every call, so only their shape is shown.
json
{  "id": "req_…",  "platform": "substack",  "action": "notes",  "results": [    {      "id": "p-•••",      "kind": "restack",      "author_username": "astralcodexten",      "author_name": "•••",      "posted_at": "2026-09-25T22:26:10.306000+00:00",      "platform": "substack",      "restacked_post": {        "title": "Your Book Review: Lee Kuan Yew's Memoirs",        "url": "https://www.astralcodexten.com/p/your-book-review-lee-kuan-yews-memoirs"      }    },    {      "id": "p-•••",      "kind": "restack",      "author_username": "astralcodexten",      "author_name": "•••",      "posted_at": "2026-09-25T06:06:18.720000+00:00",      "platform": "substack",      "restacked_post": {        "title": "Fall Meetups 2026 - Call For Meetup Organizers",        "url": "https://www.astralcodexten.com/p/fall-meetups-2026-call-for-meetup"      }    }  ],  "count": 25,  "billing": {    "charged": …,    "charged_usd": …,    "balance_after_usd": …,    …  },  "quota": { … }}

Response fields

#

Business data is in results. The table lists the fields a record can contain; values the platform does not show are never made up.

FieldMeaning
idThe record's unique ID on the platform. Unique only within one platform; IDs can repeat across platforms.
kindKeeps the platform's own meaning
textBody text with HTML removed, returned in full and never cut short (on a few platforms the list results themselves carry only an excerpt; the platform's field notes say so).
author_usernameAuthor's username (@handle), usually usable in URLs.
author_nameAuthor's display name.
like_countLikes. null means the platform or this capability does not disclose it; it is not 0.
posted_atPublish time in ISO 8601, UTC (for example 2026-08-07T12:34:56+00:00). Non-standard strings from the platform are passed through as is, so parse defensively. null means the platform does not disclose it.
platformSource platform identifier, the same as platform in the request (for example xiaohongshu, tiktok).
restacked_postKeeps the platform's own meaning
attachment_urlsKeeps the platform's own meaning

FAQ

#

What do I pass as username?

#

The writer's Substack handle, such as astralcodexten, either bare, with an @, or as a substack.com/@astralcodexten link. A publication homepage link is not the input for Substack Notes; it belongs to Substack Publication posts. The handle is the part after the @ in the writer's profile link.

Does Substack Notes return newsletter articles?

#

No. It returns the short Notes a writer posts, not long-form newsletter articles. To list a publication's articles, call the Substack Publication posts capability with the publication's homepage link; to read one article in full, pass its /p/ link to Substack Post details.

How do I keep a writer's Notes up to date?

#

Call Substack Notes on a schedule and store rows by id, so Notes you already have are recognized. Use posted_at to find what is new since your last run, and compare like_count across runs to see which Notes kept gaining likes. Parse posted_at defensively, since non-standard values are passed through as is.

Errors and billing

#
401
Missing or invalid key.
402
Insufficient balance. Top up first.
422
Invalid parameter name or value. Fix it using the suggestions in the error. No charge.
429
Per-minute request limit reached. Wait for Retry-After, then try again.
503
Could not complete. The held charge is returned to your balance. If the outcome is unknown, verify it before you retry.
200 empty
No data. No charge.

Errors

Official references

#

Used only to check objects and terms. They do not imply authorization or endorsement of EveryInfra by the platform.

  • Substack: Definition of Notes and Restack ↗

    Substack defines Notes as short-form content activity and Restack as sharing content within Notes, distinguishing them from article-by-article newsletter dispatch. Official publishing, engagement, and revenue analytics capabilities on Substack do not mean this notes read endpoint supports those operations or metrics.

    Checked 2026-09-04

Google Analytics needs consent. Privacy