Search Subreddits API

Search Reddit communities by keyword. Returns subreddit names, descriptions, icons, and URLs as JSON for $0.01 per call.

POST/v1/reddit/search-subreddits

$0.01/call

Find subreddits that match a keyword — useful for discovering where a topic is discussed before pulling posts with the Subreddit Posts API. Search results are compact: some fields (subscribers, created_at, title) can be null here. Call Subreddit Info for the full profile of a community.

Usage

const res = await fetch('https://api.yepapi.com/v1/reddit/search-subreddits', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"query": "python"}),
});
const { data } = await res.json();
console.log(data);

curl -X POST https://api.yepapi.com/v1/reddit/search-subreddits \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "python"}'

import requests

res = requests.post(
    "https://api.yepapi.com/v1/reddit/search-subreddits",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={"query": "python"},
)
print(res.json()["data"])

Request Body

Parameter	Type	Required	Description	Default
`query`	`string`	Yes	Search text (max 256 characters)	—
`cursor`	`string`	No	`cursor` from the previous response, to fetch the next page	—

Response

{
  "ok": true,
  "data": {
    "cursor": "eyJjYW5kaWRhdGVzX3JldHVybmVkIjoie1wic2VjdGlvbl8xX3BpcGVsaW5lXzBfZ2xvYmFsX21vZGlmaWVyc1wiOlwiMVwiLFwic2VjdGlvbl8xX3BpcGVsaW5lXzFfbG9jYWxfbW9kaWZpZXJzXCI6XCIwXCIsXCJzZWN0aW9uXzJfcGlwZWxpbmVfMF9zdWJyZWRk…",
    "subreddits": [
      {
        "active_users": null,
        "banner": null,
        "created_at": null,
        "created_utc": null,
        "description": "The largest Python community for Reddit! Stay up to date with the latest news, packages, and meta information relating to the Python programming language. \n---\n\nIf you have questions or are new to Pyt…",
        "icon": "https://styles.redditmedia.com/t5_2qh0y/styles/communityIcon_lctik80p96tg1.png?width=64&frame=1&auto=webp&s=92baaacc951d52b5071629852df033d53cafa5ec",
        "id": null,
        "lang": null,
        "name": "Python",
        "over_18": false,
        "subscribers": null,
        "title": null,
        "type": null,
        "url": "https://www.reddit.com/r/Python/"
      },
      {
        "active_users": null,
        "banner": null,
        "created_at": null,
        "created_utc": null,
        "description": "A subreddit for helping Python programmers",
        "icon": null,
        "id": null,
        "lang": null,
        "name": "pythonhelp",
        "over_18": false,
        "subscribers": null,
        "title": null,
        "type": null,
        "url": "https://www.reddit.com/r/pythonhelp/"
      }
    ]
  }
}

Response Fields

Field	Type	Description
`ok`	`boolean`	Whether the request succeeded
`data.subreddits`	`object[]`	Matching subreddits
`data.subreddits[].id`	`string \| null`	Subreddit ID
`data.subreddits[].name`	`string`	Subreddit name without `r/`
`data.subreddits[].title`	`string \| null`	Subreddit title
`data.subreddits[].description`	`string \| null`	Public description
`data.subreddits[].subscribers`	`number \| null`	Member count
`data.subreddits[].active_users`	`number \| null`	Users online, when Reddit reports it
`data.subreddits[].created_utc`	`number \| null`	Unix timestamp (seconds)
`data.subreddits[].created_at`	`string \| null`	ISO 8601 timestamp
`data.subreddits[].over_18`	`boolean`	Marked NSFW
`data.subreddits[].type`	`string \| null`	`public`, `restricted`, `private`, …
`data.subreddits[].lang`	`string \| null`	Language code
`data.subreddits[].url`	`string`	reddit.com URL of the subreddit
`data.subreddits[].icon`	`string \| null`	Community icon URL
`data.subreddits[].banner`	`string \| null`	Banner image URL
`data.cursor`	`string \| null`	Cursor for the next page

Pagination

Each response includes a cursor. Send the same request again with that value in cursor to get the next page. When cursor is null, there are no more results. A query with no matches returns 200 with an empty list and cursor: null. Every page is a separate $0.01 call.

Caching

Responses are cached for 15 minutes.

Errors

Status	Code	When
`400`	`VALIDATION_ERROR`	`query` is missing or longer than 256 characters
`429`	`RATE_LIMITED_UPSTREAM`	Too many requests in a short burst — retry after a few seconds
`502`	`UPSTREAM_ERROR`	Temporary problem fetching data from Reddit — retry

Failed calls are not charged.

Subreddit Info — full profile, sidebar, and posting settings
Similar Subreddits — communities related to one you already know
Popular Subreddits — the most popular and newest communities

Search Subreddits API

On this page