Docs · Subreddit search

Subreddit search

Search one subreddit's posts by keyword, returned as compact result cards.

1 credit per callFresh within 1 minuteMCP tool: reddit_subreddit_search

GEThttps://api.lurkapi.com/v1/reddit/subreddit/search

When to use this

Use it to find what one community says about a product, competitor or problem. Results are compact cards without the body; pass a result's url to post comments (reddit_post_comments) for the text and replies.

Keyword search inside one subreddit, like the search box on a community page. Results carry votes, num_comments, created_at and subreddit info.

Pagination. Pass the response's cursor back as cursor; it's null at the end.

Parameters

All parameters go in the query string.

Parameter	Description
`subreddit` stringrequired	Subreddit name without r/, e.g. `marketing`. Example `marketing`
`query` stringoptional	Keywords. Leave empty to list the subreddit's posts in `sort` order. Example `AI video`
`sort` stringoptional	Result order. `comments` = most commented. One of `relevancehottopnewcomments` Default `relevance`
`timeframe` stringoptional	Only posts from the last hour, day, week, month, year, or all time. One of `allhourdayweekmonthyear` Default `all`
`cursor` stringoptional	The `cursor` from the previous response, to get the next page.

Example request

Replace YOUR_API_KEY with your key, or set LURKAPI_KEY for the code. Get a free key.

curlJavaScriptPython

JavaScript · reads your key from LURKAPI_KEY

const params = new URLSearchParams({
  subreddit: "marketing",
  query: "AI video",
});
const res = await fetch(`https://api.lurkapi.com/v1/reddit/subreddit/search?${params}`, {
  headers: { "x-api-key": process.env.LURKAPI_KEY },
});
const data = await res.json();
if (!data.success) throw new Error(`${data.code}: ${data.error}`);
console.log(data.posts);

Python · reads your key from LURKAPI_KEY

import os
import requests

res = requests.get(
    "https://api.lurkapi.com/v1/reddit/subreddit/search",
    params={
        "subreddit": "marketing",
        "query": "AI video",
    },
    headers={"x-api-key": os.environ["LURKAPI_KEY"]},
    timeout=60,
)
data = res.json()
if not data["success"]:
    raise RuntimeError(f"{data['code']}: {data['error']}")
print(data["posts"])

Example response

A real response from this endpoint, captured from the live API and trimmed to a couple of items. Strings over 96 characters (mostly signed media URLs) are cut short and end in ….

Show the example response (3 KB)

{
  "success": true,
  "credits_remaining": 993,
  "credits_charged": 1,
  "posts": [
    {
      "id": "t3_1t673is",
      "post_id": "t3_1t673is",
      "title": "Have any of you made a documentary style video using an AI tool?",
      "url": "https://www.reddit.com/r/marketing/comments/1t673is/have_any_of_you_made…",
      "permalink": "/r/marketing/comments/1t673is/have_any_of_you_made_a_documentary_style_video/",
      "nsfw": false,
      "spoiler": false,
      "is_crosspost": false,
      "subreddit": {
        "id": "t5_2qhmg",
        "name": "marketing",
        "nsfw": false,
        "quarantined": false,
        "icon": null,
        "banner": null,
        "description": null,
        "weekly_visitors": null,
        "weekly_contributions": null
      },
      "votes": 0,
      "num_comments": 37,
      "created_at": "2026-05-07T10:59:35.000+0000",
      "created_at_iso": "2026-05-07T10:59:35.000Z",
      "thumbnail": null,
      "thumbnail_blurred": false,
      "position": 0,
      "relative_position": 0
    },
    {
      "id": "t3_1woq8xa",
      "post_id": "t3_1woq8xa",
      "title": "YouTube to start allowing A/B testing of video content",
      "url": "https://www.reddit.com/r/marketing/comments/1woq8xa/youtube_to_start_all…",
      "permalink": "/r/marketing/comments/1woq8xa/youtube_to_start_allowing_ab_testing_of_video/",
      "nsfw": false,
      "spoiler": false,
      "is_crosspost": false,
      "subreddit": {
        "id": "t5_2qhmg",
        "name": "marketing",
        "nsfw": false,
        "quarantined": false,
        "icon": null,
        "banner": null,
        "description": null,
        "weekly_visitors": null,
        "weekly_contributions": null
      },
      "votes": 32,
      "num_comments": 9,
      "created_at": "2026-09-24T02:58:53.000+0000",
      "created_at_iso": "2026-09-24T02:58:53.000Z",
      "thumbnail": null,
      "thumbnail_blurred": false,
      "position": 1,
      "relative_position": 1
    }
  ],
  "cursor": "eyJjYW5kaWRhdGVzX3JldHVybmVkIjoie1wic2VjdGlvbl8xX3BpcGVsaW5lXzBfZ2xvYmFs…"
}

Response fields

Every field of a successful response. [] marks a list: a[].b is the b of each item in a. nullable fields can be null; optional fields can be missing.

Show all 31 fields

Field	Type	Description
success	true	Always true here; errors have `success: false`.
credits_remaining	number	Your balance after this call. On anonymous playground calls: free tries left today.
credits_charged	number	Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1).
posts	object[]	Matching posts, best match first (or in `sort` order).
posts[].id	string	Fullname, e.g. `t3_1t673is`.
posts[].post_id	string	Same as id.
posts[].title	string	Post title.
posts[].url	string	The post on reddit.com. Pass it to post comments for the body and replies.
posts[].permalink	string	Path on reddit.com.
posts[].votes	number	Score (upvotes minus downvotes).
posts[].num_comments	number	Comment count when fetched.
posts[].created_at	string	Posted at, e.g. `2026-05-07T10:59:35.000+0000`.
posts[].created_at_iso	string	Posted at, ISO 8601.
posts[].nsfw	boolean	Marked NSFW.
posts[].spoiler	boolean	Marked as a spoiler.
posts[].is_crosspost	boolean	Always false: search results don't say whether a post is a crosspost.
posts[].thumbnail	stringnullable	Preview image URL; null for posts without media.
posts[].thumbnail_blurred	boolean	Always false: search results don't include it.
posts[].position	number	Rank in the results, from 0.
posts[].relative_position	number	Rank as Reddit reports it; usually equal to position.
posts[].subreddit	object	The subreddit the post is in.
posts[].subreddit.id	stringnullable	Subreddit fullname, `t5_` + id.
posts[].subreddit.name	string	Subreddit name without r/.
posts[].subreddit.nsfw	boolean	The subreddit is NSFW.
posts[].subreddit.quarantined	boolean	The subreddit is quarantined.
posts[].subreddit.icon	stringnullable	Subreddit icon URL, when the result shows one.
posts[].subreddit.banner	stringnullable	Always null here; get it from subreddit details.
posts[].subreddit.description	stringnullable	Always null here; get it from subreddit details.
posts[].subreddit.weekly_visitors	numbernullable	Always null here; get it from subreddit details.
posts[].subreddit.weekly_contributions	numbernullable	Always null here; get it from subreddit details.
cursor	stringnullable	Pass as `cursor` for the next page. null on the last page.

Pagination

Pass the response's cursor back as cursor, with the other parameters unchanged, for the next page. It's null on the last page. Each page costs 1 credit.

The first five pages, in JavaScript

let cursor = null;
for (let page = 1; page <= 5; page++) {
  const params = new URLSearchParams({ subreddit: "marketing", query: "AI video" });
  if (cursor) params.set("cursor", cursor);
  const res = await fetch(`https://api.lurkapi.com/v1/reddit/subreddit/search?${params}`, {
    headers: { "x-api-key": process.env.LURKAPI_KEY },
  });
  const data = await res.json();
  if (!data.success) throw new Error(`${data.code}: ${data.error}`);
  console.log(data.posts);
  cursor = data.cursor;
  if (!cursor) break; // last page
}

Caching and freshness

Responses are cached for up to 1 minute, so a repeat call within that window can return the same data. It still costs 1 credit.

Errors

Errors return { success: false, error, code, docs } with the HTTP status below. Validation errors, 401/402/429 rejections and 5xx failures are free; not_found is charged (how charging works). All error codes.

Status	Code	Meaning
401	`missing_api_key`	No API key. Send it in the `x-api-key` header.
401	`invalid_api_key`	The key is unknown or was revoked.
402	`insufficient_credits`	Not enough credits for this call. Buy a pack or wait for tomorrow's top-up.
405	`method_not_allowed`	Endpoints take GET with query params.
429	`rate_limited`	Too many calls at once. Wait for the `retry-after` seconds, then retry.
500	`internal_error`	Something broke on our side. Retry; 5xx errors are free.
502	`upstream_error`	The platform didn't give a usable answer. Retry; 5xx errors are free.
503	`upstream_busy`	All our connections to the platform are busy. Retry in a few seconds; 5xx errors are free.
504	`upstream_timeout`	The platform took over 30 seconds to answer. Retry; timeouts are free.

Use it in Claude

Once LurkAPI is connected to Claude, this endpoint is the reddit_subreddit_search tool. Ask in plain English, for example:

Ask Claude

Use LurkAPI's reddit_subreddit_search with subreddit "marketing", query "AI video" and summarize what you find.

Claude calls reddit_subreddit_search with arguments like these, and each call costs 1 credit:

Tool arguments

{
  "subreddit": "marketing",
  "query": "AI video"
}

Tool results skip nulls and empty lists to save tokens.