---
title: "Search Substack Posts"
method: GET
path: "/v1/substack/posts"
tags: ["Substack"]
---

# Search Substack Posts

`GET /v1/substack/posts`

## Request

- Base URL: `https://apidirect.io`
- URL: `https://apidirect.io/v1/substack/posts`
- Auth: API key in header `X-API-Key`

Search Substack posts by keyword across every publication. Returns post title, subtitle, author, publication, publication date, engagement (likes, comments, restacks), paywall status, word count, cover image and tags, plus the publications related to the query. Supports a time window from the past day to the past year.

**Price:** $0.003 per request. **Free tier:** 50 requests/month.

## Query parameters

- `query` string, required
- `page` integer
- `posted_ago` '24h' | '7d' | '30d' | '12m'
- `language` string
- `get_sentiment` boolean

## Response `200`

Successful response

- SearchSubstackResponse: Inferred from a live response. Any field can be null or absent, and new fields may be added at any time.
  - `posts` object[], nullable
    - `title` string, nullable
    - `subtitle` string, nullable
    - `url` string, nullable
    - `date` string, nullable
    - `author` string, nullable
    - `author_name` string, nullable
    - `author_id` string, nullable
    - `author_url` string, nullable
    - `source` string, nullable
    - `domain` string, nullable
    - `snippet` string, nullable
    - `likes` number, nullable
    - `comments` number, nullable
    - `restacks` number, nullable
    - `reactions` object, nullable
      - `❤` number, nullable
    - `is_paid` boolean, nullable
    - `audience` string, nullable
    - `type` string, nullable
    - `wordcount` number, nullable
    - `lang` string, nullable
    - `cover_image_url` string, nullable
    - `podcast_url` string, nullable
    - `podcast_duration` number, nullable
    - `tags` string[], nullable
    - `publication` string, nullable
    - `publication_id` string, nullable
    - `publication_url` string, nullable
    - `slug` string, nullable
    - `post_id` string, nullable
    - `authors` object[], nullable
      - `username` string, nullable
      - `name` string, nullable
      - `user_id` string, nullable
    - `replies` number, nullable
    - `audio_url` string, nullable
    - `podcast_image_url` string, nullable
    - `video_duration` number, nullable
  - `publications` object[], nullable
    - `publication_id` string, nullable
    - `name` string, nullable
    - `subdomain` string, nullable
    - `url` string, nullable
    - `custom_domain` string, nullable
    - `description` string, nullable
    - `logo_url` string, nullable
    - `cover_image_url` string, nullable
    - `author` string, nullable
    - `author_name` string, nullable
    - `author_id` string, nullable
    - `author_url` string, nullable
    - `subscriber_count` number, nullable
    - `subscriber_count_label` string, nullable
    - `ranking_detail` string, nullable
    - `paid_subscriber_band` string, nullable
    - `paid_subscriber_floor` number, nullable
    - `bestseller_tier` number, nullable
    - `is_bestseller` boolean, nullable
    - `paid_enabled` boolean, nullable
    - `plans` object[], nullable
      - `interval` string, nullable
      - `amount` number, nullable
      - `currency` string, nullable
    - `has_podcast` boolean, nullable
    - `language` string, nullable
    - `type` string, nullable
    - `twitter_handle` string, nullable
    - `created_at` string, nullable
    - `first_post_date` string, nullable
    - `source` string, nullable
    - `domain` string, nullable
    - `author_pic_url` string, nullable
    - `founding_plan_name` string, nullable
    - `has_chat` boolean, nullable
    - `has_recommendations` boolean, nullable
    - `logo_url_wide` string, nullable
    - `podcast` unknown
    - `sections` unknown[], nullable
      - unknown
  - `query` string, nullable
  - `page` number, nullable
  - `has_next_page` boolean, nullable
  - `count` number, nullable

## Other responses

- `400`: Bad request: a required parameter is missing or a value is invalid (code: missing_parameter or invalid_parameter).
- `401`: Unauthorized: the API key is missing or invalid (code: missing_api_key or invalid_api_key).
- `402`: Free tier used up for this endpoint and no payment method on file (`payment_required`).
- `403`: Account blocked after a failed payment (`account_blocked`).
- `429`: Rate limit exceeded, or too many concurrent requests for this endpoint
- `500`: Internal server error
- `502`: Temporary failure retrieving Substack data. Please retry shortly.
- `503`: Service unavailable: the data source is temporarily unavailable
- `504`: The request timed out

---

[API](https://skmtc.dev/apidirect/apis/api-direct.md) · [All operations](https://skmtc.dev/apidirect/apis/api-direct/llms.txt) · [OpenAPI document](https://skmtc.dev/apidirect/apis/api-direct/revisions/fa8c68d70bd0?raw)