Docs · Subreddit posts

Subreddit posts

A subreddit's feed (hot, new, top, rising or best), with titles, text, scores and comment counts.

1 credit per callFresh within 1 minuteMCP tool: reddit_subreddit_posts

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

When to use this

Use it to track what a community talks about. About 25 posts per page; pass after for more. timeframe only applies with sort=top. Missing, private and banned subreddits return an empty posts list.

One page of a subreddit's feed as sorted on reddit.com, with titles, text, scores and comment counts.

Pagination. Pass the response's after back as after for the next page; after is 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`
`sort` stringoptional	Feed order, as on reddit.com. One of `besthotnewtoprising` Default `hot`
`timeframe` stringoptional	Time window for `sort=top`: hour, day, week, month, year or all. One of `allhourdayweekmonthyear` Default `all`
`after` stringoptional	The `after` from the previous response, to get the next page.
`trim` booleanoptional	`true` omits `selftext_html` for a smaller response. One of `truefalse` Default `false`

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",
});
const res = await fetch(`https://api.lurkapi.com/v1/reddit/subreddit?${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",
    params={
        "subreddit": "marketing",
    },
    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": 995,
  "credits_charged": 1,
  "posts": [
    {
      "id": "1wtsnuh",
      "name": "t3_1wtsnuh",
      "title": "Networking group recs?",
      "author": "Party4Chai",
      "author_fullname": "t2_49qg9o4t",
      "subreddit": "marketing",
      "subreddit_id": "t5_2qhmg",
      "subreddit_name_prefixed": "r/marketing",
      "permalink": "/r/marketing/comments/1wtsnuh/networking_group_recs/",
      "url": "https://www.reddit.com/r/marketing/comments/1wtsnuh/networking_group_recs/",
      "domain": "self.marketing",
      "score": 3,
      "ups": 3,
      "upvote_ratio": 0.8,
      "num_comments": 10,
      "created": 1790733391,
      "created_utc": 1790733391,
      "is_self": true,
      "is_video": false,
      "over_18": false,
      "spoiler": false,
      "stickied": false,
      "locked": false,
      "link_flair_text": "Question",
      "link_flair_background_color": "#94E044",
      "selftext": "I was in Monday Girl and unfortunately they just don't offer enough in t…",
      "selftext_html": "<p>I was in Monday Girl and unfortunately they just don&#39;t offer enou…",
      "thumbnail": null,
      "total_awards_received": 0
    },
    {
      "id": "1wtfnyr",
      "name": "t3_1wtfnyr",
      "title": "How to make my booth more interesting?",
      "author": "Fantastic_Shoe_3189",
      "author_fullname": "t2_dvo38ecf",
      "subreddit": "marketing",
      "subreddit_id": "t5_2qhmg",
      "subreddit_name_prefixed": "r/marketing",
      "permalink": "/r/marketing/comments/1wtfnyr/how_to_make_my_booth_more_interesting/",
      "url": "https://www.reddit.com/r/marketing/comments/1wtfnyr/how_to_make_my_booth_more_interesting/",
      "domain": "self.marketing",
      "score": 10,
      "ups": 10,
      "upvote_ratio": 0.92,
      "num_comments": 42,
      "created": 1790701262,
      "created_utc": 1790701262,
      "is_self": true,
      "is_video": false,
      "over_18": false,
      "spoiler": false,
      "stickied": false,
      "locked": false,
      "link_flair_text": "Question",
      "link_flair_background_color": "#94E044",
      "selftext": "Hey all,\n\nRecently my team has been attending a conference circuit in wh…",
      "selftext_html": "<p>Hey all,</p><p>Recently my team has been attending a conference circu…",
      "thumbnail": null,
      "total_awards_received": 0
    }
  ],
  "after": "t3_1wnhso4"
}

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 36 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[]	One page of posts, in feed order.
posts[].id	string	Post id, e.g. `1wtfnyr`.
posts[].name	string	Fullname, `t3_` + id. Subreddit listings paginate with it.
posts[].title	string	Post title.
posts[].author	stringnullable	Username, without u/; null if unknown.
posts[].author_fullname	stringnullable	Author's account fullname, `t2_` + id; null if unknown.
posts[].subreddit	string	Subreddit name without r/, e.g. `marketing`.
posts[].subreddit_id	stringnullable	Subreddit fullname, `t5_` + id.
posts[].subreddit_name_prefixed	stringnullable	e.g. `r/marketing`.
posts[].permalink	string	Path on reddit.com; prepend https://www.reddit.com.
posts[].url	string	The link a link post points to, or the post itself for text posts.
posts[].url_overridden_by_dest	stringoptional	Outbound link, on link posts only.
posts[].domain	stringnullable	`self.<subreddit>` for text posts, else the linked site.
posts[].selftext	string	Post body as plain text. Empty for link posts.
posts[].selftext_html	stringnullable · optional	Post body as HTML. Omitted with trim=true.
posts[].score	number	Upvotes minus downvotes.
posts[].ups	number	Same as score.
posts[].upvote_ratio	numbernullable	Share of votes that are upvotes, 0–1.
posts[].num_comments	number	Comment count when fetched.
posts[].created	number	Posted at, Unix seconds.
posts[].created_utc	number	Posted at, Unix seconds.
posts[].is_self	boolean	A text post rather than a link.
posts[].is_video	boolean	A video post.
posts[].is_gallery	booleanoptional	Present (true) on image galleries; absent otherwise.
posts[].over_18	boolean	Marked NSFW.
posts[].spoiler	boolean	Marked as a spoiler.
posts[].stickied	boolean	Pinned by moderators.
posts[].locked	boolean	Locked: no new comments allowed.
posts[].link_flair_text	stringnullable	Post flair, e.g. "Question"; null without flair.
posts[].link_flair_background_color	stringnullable	Flair color as a hex code, e.g. #94E044; null without flair.
posts[].thumbnail	stringnullable	Preview image URL; null for posts without media.
posts[].total_awards_received	number	Awards the post received.
after	stringnullable	Pass as `after` for the next page. null on the last page.

Pagination

Pass the response's after back as after, 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 after = null;
for (let page = 1; page <= 5; page++) {
  const params = new URLSearchParams({ subreddit: "marketing" });
  if (after) params.set("after", after);
  const res = await fetch(`https://api.lurkapi.com/v1/reddit/subreddit?${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);
  after = data.after;
  if (!after) 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_posts tool. Ask in plain English, for example:

Ask Claude

Use LurkAPI's reddit_subreddit_posts with subreddit "marketing" and summarize what you find.

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

Tool arguments

{
  "subreddit": "marketing"
}

Tool results skip nulls and empty lists to save tokens, and trim defaults to true.