Search Substack Notes API

Endpoint

GET /v1/substack/notes

Parameters

query *

Search keyword (max 500 characters)

sort_by

Sort order: most_recent, top (default: most_recent)

pages

Number of pages to fetch, 1-250 (default: 1). Each page returns up to 12 notes; you are billed per page returned.

get_sentiment

Set to true to add AI emotion analysis (Plutchik's Wheel) to each result. Adds +$0.001 per page to the cost. Returns emotion scores, dominant emotion, intensity, and polarity.

Response fields

notes

Array of matching notes

note_id

Note ID

body

Note text

date

Date and time posted (UTC)

author

Author's handle

author_name

Author's display name

author_id

Author's user ID

author_url

Link to the author's profile

source

"Substack"

domain

"substack.com"

likes

Number of likes

replies

Number of replies

restacks

Number of restacks

reactions

Reaction counts by emoji

author_pic_url

Author's profile picture URL

author_bestseller_tier

Author's bestseller badge tier: 0, 100, 1000 or 10000

lang

Language code

attachments

Media and quoted items. Each has type (image, video, link, post, note, publication) and url, plus title or dimensions where relevant

publication

The author's primary publication

url

Direct link to the note

query

The search keyword

sort_by

The sort order used

pages

Number of pages returned

count

Number of notes returned

Example Request

curl "https://apidirect.io/v1/substack/notes?query=claude%20code&pages=1"   -H "X-API-Key: YOUR_API_KEY"

import requests

response = requests.get(
    "https://apidirect.io/v1/substack/notes",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"query": "claude code", "pages": 1}
)
print(response.json())

Example Response

{
  "count": 9,
  "notes": [
    {
      "attachments": [
        {
          "height": 3000,
          "type": "image",
          "url": "https://substack-post-media.s3.amazonaws.com/public/images/3b20c7ab-894d-4fac-8c71-a770e65b2cd3_2400x3000.webp",
          "width": 2400
        }
      ],
      "author": "aakashgupta",
      "author_bestseller_tier": 0,
      "author_id": "4429439",
      "author_name": "Aakash Gupta",
      "author_pic_url": "",
      "author_url": "https://substack.com/@aakashgupta",
      "body": "Claude Code is the best way to use AI.\n\nHere's your complete guide:\n\n1. Stop working in chat windows\n\nOpen terminal in y…",
      "date": "2026-10-12 05:00:03",
      "domain": "substack.com",
      "lang": "en",
      "likes": 1,
      "note_id": "358840474",
      "publication": "Product Growth",
      "reactions": {
        "❤": 1
      },
      "replies": 0,
      "restacks": 0,
      "source": "Substack",
      "url": "https://substack.com/@aakashgupta/note/c-358840474"
    }
  ],
  "pages": 1,
  "query": "claude code",
  "sort_by": "most_recent"
}

Frequently asked questions

Why fewer than 12 notes on a page?

Substack's search feed mixes posts into these pages; only the notes are returned. Posts are searchable with Search Posts.

Is there a time filter?

No. Substack's notes search has no date window; use sort_by=most_recent and stop when the dates get older than you need.

How does pricing work?

You only pay for successful requests. The Search Substack Notes API costs $0.003 per page. There are no monthly fees or commitments. You get 50 free requests per endpoint every month.

Do I need a credit card to start?

No. You can sign up and use the free tier (50 requests/endpoint/month) without adding a payment method. You only need to add a card when you want to exceed the free tier.

Are there rate limits?

Yes, there's a concurrency limit of 10 simultaneous requests per endpoint per user. If you need more, just get in touch.