How much credit this API key has left, before spending any. Returns the account's remaining credit balance and usage totals. FREE: this call is not metered and never costs a credit, so call it whenever you are about to run something expensive rather than guessing. Use it to decide whether a planned batch fits in the remaining balance, and to tell the user how much is left if a call returns 402. A 402 from any other tool means the balance is exhausted; its response carries a top-up URL to give the user.

Bulk-fetch posts by their t3_ fullnames in ONE call (up to 100), instead of a request per post. Pass a comma-separated list of fullnames you already have from a search or listing to hydrate them. Returns posts with title, author, score, comment count, and permalink, the same post shape as the listing endpoints. The result is NOT always one-to-one with your request, so read meta: listing_status is complete only when every fullname came back, truncated is the boolean to branch on, and missing_fullnames names exactly which ids did not. Example: fullnames='t3_abc123,t3_def456'.

Genuine comment search: returns the ACTUAL comments whose body matches your keyword, sorted by score (highest first), with body, score, author, a comment-deep permalink, and the parent post. Unlike reddit_search_comments (which returns the parent posts, a Reddit limitation), this fetches each matching post's comment tree and filters the comment bodies for you, so you get first-hand opinions and answers directly. Premium call (it fans out into several reads): limit sets how many parent POSTS to expand, 1-25 (default 5), not how many comments come back. To go deeper than one call, paginate: pass the response's after cursor back as after to expand the NEXT batch of parent posts. max_comments optionally caps how many comments come back (the top-scored are kept). Matching is on the visible comment text at word boundaries (link URLs are ignored), so a result always mentions your query where a reader can see it. Best-effort: a deleted or deeply-nested comment may be missed (meta.truncated flags when a tree was too deep). Set group_by='author' for the research mode that returns WHO is talking about your query (distinct people ranked by matching-comment count) instead of a flat comment list, capped by max_authors. Example: q='best mechanical keyboard' sort='top'.

Check the status of a feedback report this account sent earlier (the server id returned by reddit_feedback_send action "send"): status new, triaged, shipped or declined, the team's response text if any, and updated_at, which moves only when the team acts on it. Free per call. 404 if the id is not on this account.

List the feedback reports this account has sent, newest first, with each one's current status. Use it to RECOVER A LOST ID: the server id is returned only once, when a report is sent, so this is the way back to a report whose id was not kept. Also the way to answer "did that report actually land" and "has the team looked at it yet". Optionally filter by status or type, and page with the cursor from a previous response. Free per call, never metered. Returns {feedback: [...], count, limit, next_cursor}; page by passing next_cursor back as cursor until it is null; an account that has filed nothing gets an empty list and a 200, not an error. Note this lists SENT reports on the server, which is different from reddit_feedback_send action="list", which shows unsent local drafts on this machine.

Report a product problem or gap in redditapis.com to its team from inside this session, the way Claude Code's own feedback tool works: a report is DRAFTED to a local queue first (action "draft", the default) and SENT only after the user reviews it. Drafting sends nothing, needs no confirmation, and should not be announced mid-task. WHEN TO DRAFT, only at high-signal moments: a redditapis tool call failed with an error that was not a missing key (401), credits (402) or a rate limit (429), and the user had to work around it; the user asked for something no redditapis tool covers; a documented field came back empty or wrong; the user was clearly frustrated with a result. One draft per distinct issue, never twice for the same one. FORMAT for details, four labelled bullets in this order: 'What happened:' observed vs expected, exact error text if short. 'What the user said:' quoted verbatim, or 'user did not comment'. 'Repro:' the minimal call that reproduces it. 'Evidence:' tool name, endpoint, HTTP status, request id (the last failing call is attached automatically where you leave a gap). Facts only: no guessing, no API keys or secrets, no personal names. REVIEW: when the user asks to see or send feedback, call action "list", then action "send" with ONLY the draft ids the user named in their own message, or action "discard". Sending posts each draft to POST /feedback (free, not metered) and returns a server id that reddit_feedback_get can check later.

Read YOUR OWN Reddit home feed, the front page your subscriptions produce. Every other read tool here is served from a shared pool of accounts, so it cannot answer 'what is on my feed' -- this one sends your session instead. REQUIRES your own Reddit session: call POST /api/reddit/login on the REST API first (not an MCP tool) and pass the reddit_session and loid cookies it returns. Without them this returns 400, deliberately, because Reddit's logged-out front page is a different feed belonging to nobody rather than a thinner version of yours. Same post shape and after cursor as reddit_subreddit_posts. For a PUBLIC community feed use reddit_subreddit_posts instead. Example: sort='best' limit=25.

Create a new Reddit monitor: watch one or more subreddits, or ALL of Reddit, for new posts (or comments, via kind) matching a filter, and get every match delivered to a webhook you've registered with reddit_monitor_webhook_create. Omit subreddit and set q for a sitewide keyword monitor covering every subreddit at once (posts only). By default matches go to EVERY active webhook on your account; pass webhook_ids to route this monitor's matches to only specific webhook(s). Every redditapis.com account holds a free entitlement of ONE all-of-Reddit post watch at a 60s cadence (up to 10,000 deliveries a day), so no subscription is needed to create that monitor. Naming a subreddit, matching comments, a faster cadence and any additional watch require a paid plan. Needs at least one monitor slot free (see reddit_monitor_list's slots). Forward-looking only from the moment of creation, or from baseline_item_id if given -- it never backfills posts that already existed. Returns the created monitor (with its id) on success, or subscription_required (402) if the account holds no recognised entitlement at all, subreddit_scope_requires_paid_plan (402) if a free account named a subreddit, monitor_slots_exhausted (402) if the plan's slot limit is reached, sitewide_slots_exhausted (402) if the plan's separate sitewide cap is reached, distinct_subreddit_limit_reached (402) if the account already watches as many DIFFERENT subreddits as the plan covers (the limit counts distinct subreddits across all your monitors, not monitors, and the same subreddit in two monitors counts once; see reddit_monitor_list's slots.distinct_subreddits_total), sitewide_comment_monitoring_not_available (501) if a sitewide monitor asks for comments, subreddit_reserved (400) if subreddit names 'all', subreddit_not_found (400) if a named subreddit does not exist, or webhook_not_found (400) if a webhook_ids entry is not yours.

Delivery history: the actual Reddit posts a monitor's webhook has received (or attempted), newest first, including the real post content (title, subreddit, permalink, author). Answers 'what did I actually get sent', not just 'how many' (see reddit_monitor_health for counts). Every delivered item also carries payload.items[].enrichment: a relevance.score (0-1, how much of THIS monitor's own keyword criteria the item matched -- not a model's confidence), a sentiment (polarity -1 to 1 plus a positive/negative/mixed/neutral label), and an intent.tag (question, recommendation_request, complaint, promotion, praise, or discussion). All three are deterministic keyword/lexicon/rule heuristics computed at no extra cost -- each carries its own method field and NONE of them is a machine-learning or LLM call, so do not describe a score here as ML-derived. Omit id to aggregate history across every monitor you own.

Per-monitor health: whether it's active, its poll cadence, when it last matched something, and delivery counts for the last 24h (delivered_24h, failed_24h, suppressed_24h) plus whether its delivery ceiling has been hit (ceiling_reached) and what that ceiling is (daily_delivery_ceiling). suppressed_24h COUNTS TWO DIFFERENT THINGS AND suppressed_breakdown SPLITS THEM: ceiling (the monitor's daily cap was reached) and stale (the item was already older than the freshness window when we first saw it, so it was withheld rather than delivered as if it were new). A stale withhold is the usual reason a monitor's delivered count sits far below its matched count with no error anywhere, and it is the freshness gate working as intended -- nothing failed, the endpoint is fine, no limit on the plan rejected them, and retrying cannot recover the items. Do NOT read suppressed_24h > 0 as 'this monitor is over its limit': ceiling_reached is the field that answers that, and a stale withhold deliberately does not set it. When suppressed_breakdown.resolved is false the counts do not add up to the total and unresolved_reason says why, so do not report a split off them; ceiling_reached stays conservative in that case rather than being cleared. THOSE COUNTS ONLY COVER POSTS WE FETCHED. A post we never fetched was never matched and leaves no row behind, so it is absent from all three counters rather than counted in any of them -- zeros there mean 'no matches recorded', never 'nothing was missed'. coverage_24h is the separate field that speaks to fetching, and its status is the one to read first: complete (every poll reached the point where the previous poll finished), degraded (at least one poll was truncated and posts were lost unrecoverably -- see gaps[], posts_in_window_at_least and the estimated posts_missed_estimate), partial (nothing found, but not every kind of loss was checked -- see unobserved_events), or unknown (the check could not be run at all -- see reason). Do NOT report a monitor as healthy on unknown or partial, and do not treat a null count as zero: both mean the question went unanswered. coverage_24h is fed by the poll log and covers BOTH ways a poll loses posts unrecoverably (listing_exhausted, where Reddit stopped serving older posts, and poll_overflow, where the feed outran one poll's page budget); observed_events names what was actually checked, and a status of complete is only ever awarded when both were. WHAT complete DOES AND DOES NOT ESTABLISH: it means every poll that RAN got back to where the previous poll finished, AND that every feed was actually polled. The second half is stream_liveness, the field to read FIRST. coverage_24h is computed from the poll log, and a feed that is never polled writes nothing to that log, so it records no truncated poll and the coverage read comes back clean -- identical to a healthy monitor. stream_liveness reads a different source (the polling registry plus the per-feed last-successful-poll stamp), neither of which a poll that never ran can produce. Its status is live (every feed checked within three times its own interval), degraded (at least one is not: see streams[] for never_polled, stalled or unregistered per feed), or unknown (could not be established, including streams_awaiting_first_poll on a monitor created moments ago, which clears itself). coverage_24h can never read complete while this is anything but live. Do NOT report a monitor as healthy unless stream_liveness.status is live, and do not read a zero delivery count on a never_polled feed as a quiet subreddit: nothing was checked, so nothing could match. gaps[] IS A SAMPLE, NOT THE WHOLE LIST: it carries the most recent gaps only, gaps_returned says how many are in it, gaps_truncated says whether more exist, and gap_events_24h is always the true total. Count gaps from gap_events_24h and never from the length of gaps[]. FINALLY, cadence ANSWERS 'AM I BEING CHECKED AS OFTEN AS I PAY TO BE', which none of the fields above can. Cadence is a priced feature, so this is the field that says whether the monitor is being served the interval its plan sells. promised_cadence_s is the floor the account's CURRENT plan includes and requested_cadence_s is what this monitor is actually set to; meets_entitlement false means the monitor is set slower than the plan allows, which happens because a plan upgrade does NOT re-cadence monitors that already exist -- the fix is to set cadence_s on the monitor, and a deliberately slower cadence is also a legitimate choice. last_checked_s_ago, freshness_ratio and within_margin describe the slowest feed feeding this monitor, named in slowest_stream. READ freshness_reading BEFORE QUOTING ANY OF THEM: it is ONE INSTANTANEOUS SAMPLE, not an average and not a sustained verdict, so a single reading past the margin is not by itself proof of under-service. Every one of these is TRI-STATE and null NEVER means fine: a null within_margin or meets_entitlement means the question could not be answered, and unknown_reason says why. Do not report a monitor as on-cadence on a null.

List every monitor on the caller's account, with each one's filter, active state, and cadence, plus a slots object ({used, total, tier}) showing how many monitor slots are purchased vs in use. Reading your own list never requires an active plan (a lapsed subscription shows an empty or paused list, not an error). webhook_ids NULL DOES NOT MEAN THE MONITOR HAS NO DESTINATION: null is the default and means matches go to EVERY active webhook on the account, which is the normal healthy state. A non-empty array narrows delivery to just those webhook ids. Never report a monitor as having no delivery target on the strength of a null here -- to see where a monitor's matches actually went, read reddit_monitor_deliveries, whose rows carry the resolved webhook_id.

Delete a monitor. There is no undo endpoint -- it stops matching immediately, its slot is freed for a new monitor, and it disappears from reddit_monitor_list. Its past deliveries are NOT erased: they remain queryable via reddit_monitor_deliveries (both scoped by monitor_id and in the aggregate, no-id view) forever. Returns 404 monitor_not_found if the id does not exist or is not yours.

Update an existing monitor: pause/resume it (active), change its poll interval (cadence_s), switch between posts and comments (kind), replace its filter entirely, or re-target which webhook(s) it delivers to (webhook_ids). IMPORTANT: if you pass ANY filter field (subreddit, q, kind, domain, etc.), it REPLACES the whole filter, it does not merge with the existing one -- resupply every field you want kept, including subreddit AND kind (omitting kind reverts that monitor to posts-only). Same rule for webhook_ids: passing it REPLACES the monitor's targeting outright (an empty array clears back to 'every active webhook'); omitting it entirely leaves the monitor's existing targeting untouched. Omit all filter/webhook_ids fields to change only active/cadence_s. Returns 404 monitor_not_found if the id does not exist or is not yours, or 400 webhook_not_found if a webhook_ids entry is not yours.

Register a delivery target for monitors to send matches to. Requires an active monitoring plan (a webhook with no plan could never receive anything). Returns the webhook with its signing secret SHOWN ONCE -- store it immediately, it is never returned again by reddit_monitor_webhook_list. HTTPS only; the URL is re-validated (including a fresh DNS check) at every delivery, not just at creation.

Permanently delete a webhook. Any monitor still pointing at it will fail to deliver until repointed at a different webhook -- this does NOT cascade-delete or pause the monitors using it. Cannot be undone. Returns 404 webhook_not_found if the id does not exist or is not yours.

List every webhook registered on the caller's account. Never returns the signing secret (shown once, at creation, by reddit_monitor_webhook_create).

Send a one-off test delivery to a registered webhook (rate-limited to 10/min) so you can confirm it's wired up correctly before waiting for a real match. Uses the webhook's kind to format the test payload the same way a real delivery would. On failure the response carries reason and status plus TWO fields that say what to actually do: hint, our sentence naming the fix (most often that the target's kind does not match its host, which no test can succeed through), and detail, a bounded, sanitised copy of what the destination itself replied. Report hint to the user rather than the bare reason -- http_error with a 400 names no field, no value and no remedy. Returns 404 webhook_not_found if the id does not exist or is not yours, or webhook_url_rejected if the URL fails re-validation (e.g. now resolves to a private address).

Fetch a single Reddit post by its id. Returns the full post object (title, author, score, text, permalink, subreddit, url). Use when you already have a post id and want its details. Example: id='abc123' (the base-36 id, no t3_ prefix).

Fetch a single post and its comment tree by permalink. Returns the post plus threaded comments (author, body, score, replies) and an after cursor. Use after finding a post via search/listing to read the full discussion. Pass the post's permalink from a prior result.

Is a post still publicly visible, or did it quietly stop being so? A removed Reddit post still returns when you fetch it by id, so asking the post does not answer this. This fetches the post and then one page of its author's submitted listing and compares them. Returns a verdict of live, not_visible or undecidable, a plain-language reason, and a confident flag. It deliberately never says WHY a post is not visible: a moderator removal, an admin removal, a spam filter and an author who has hidden their history are indistinguishable from outside. undecidable is a real answer, not a failure. Two upstream calls, billed as one $0.004 dual read.

Search Reddit posts across all of Reddit or within one subreddit. Returns matching posts with author, score, comments, permalink, and an after cursor. Use for topic/keyword research, brand monitoring, or finding discussions. Scope to a community with subreddit. Optional advanced filters narrow the results by minimum/maximum score, comment count, media type, and post flags, with an optional re-sort of the page. Because filters are applied to the returned page, the response then carries a meta object with page-completeness counts, so a filtered result is never mistaken for the whole set; paginate with after to filter more. Example: q='rust vs go' sort='top' t='year'.

Search Reddit by COMMENT text. Reddit's comment search matches your keyword against comment bodies but returns the PARENT POSTS, not the individual comments, so each result is a post whose discussion mentions your query, carrying that post's title, selftext, score, and comment count. Use it to surface threads where a topic comes up in the replies that plain post-title search would miss. Reddit does not expose which specific comment matched or its text, so this returns posts, not comment bodies. For the actual comment bodies, use reddit_deep_comment_search. Example: q='best mechanical keyboard' sort='top'.

Search for subreddits (communities) by name or topic. Returns matching subreddits with title, subscriber count, description, and NSFW flag. Use to discover where a topic is discussed before listing or searching its posts. Example: q='machine learning'.

Search Reddit posts filtered to media (images, video, gifs). Returns media posts with the media URL/type, author, score, and the post url. Use kind to narrow to a media type. Example: q='aurora borealis' kind='image'.

Search for Reddit users (redditors) by name or keyword. Returns matching accounts with username, karma, and account age. Use to find a person's handle before fetching their profile or comments. Example: q='spez'.

Fetch a subreddit's public metadata by name (Reddit's /r//about data). Returns the subreddit's title, public description, subscriber count, active-user count, creation timestamp, type, and NSFW flag. Use it to size or vet a community before listing or searching its posts. Example: name='python'.

Stream the NEWEST comments across an entire subreddit (Reddit's /r//comments feed), not one post's thread. Returns comments with body, author, score, subreddit, the parent post link, and timestamp, plus an after cursor. Poll it to catch new comments in a community as they are posted. Example: name='python'.

Fetch a subreddit's moderator team by name (Reddit's /r//about/moderators data). Returns a moderators list, each with name, id, mod_permissions, flair_text, and added (when they joined the mod team). Use it to see who moderates a community. Example: name='python'.

List posts from a subreddit by sort order. Use this to read a community's feed: newest, hot/trending, top-of-week, rising, etc. Returns post title, author, score, comment count, and permalink, plus an after cursor for paging. When after comes back null the response carries listing_status: complete means no older posts and is only claimed when the whole run came back in under one page, truncated means Reddit's cap cut you off, and unknown means we cannot tell, so do NOT report unknown as the end of the data. A busy feed that Reddit simply stops serving reports unknown, not complete, so treat unknown as an incomplete answer and widen across sorts, timeframes or search rather than paging deeper. Example: subreddit='programming' sort='top' t='week'.

Fetch a subreddit's posting rules by name (Reddit's /r//about/rules data). Returns a rules list, each with name, description, what it applies to (posts, comments, or all), violation reason, priority, and creation date, plus a site_rules list of Reddit's site-wide rules. Use it to check a community's rules before posting or commenting. Example: name='python'.

Browse Reddit's default front-page set of subreddits, no keyword needed. Returns a subreddits list (each with name, title, subscriber count, description, type, and NSFW flag) plus an after cursor for paging. This BROWSES the default communities; use reddit_search_communities instead to SEARCH communities by keyword.

Browse the newest subreddits, the communities most recently created, no keyword needed. Returns a subreddits list (each with name, title, subscriber count, description, type, and NSFW flag) plus an after cursor for paging. This BROWSES communities by recency; use reddit_search_communities instead to SEARCH communities by keyword.

Browse the most-subscribed, trending subreddits right now, no keyword needed. Returns a subreddits list (each with name, title, subscriber count, description, type, and NSFW flag) plus an after cursor for paging. This BROWSES communities by popularity; use reddit_search_communities instead to SEARCH communities by keyword.

Get the TOP posts of a subreddit for a time window. Shorthand for the highest-scoring posts of a community. Returns posts with score, author, comments, and permalink plus an after cursor. Example: name='science' t='month'.

Fetch a subreddit's wiki page by name and page (Reddit's /r//wiki/ data). Returns a single object with content_md and content_html, a may_revise flag, and the last revision (revision_id, revision_date, revised_by, reason). Use it to read a community's wiki, such as its rules or FAQ. The page may be multi-segment, for example index, rules, or config/sidebar. Example: name='python', page='index'.

List a Reddit user's recent comments. Returns comments with body, score, subreddit, parent link, and timestamp plus an after cursor. Use to understand what a redditor talks about or to gather their opinions. Example: name='spez' sort='top'.

List the posts and comments a Reddit account has received an award (gold) on. PRIVATE data -- Reddit only serves it to the account that owns it, so you must be logged in as name (see the reddit_session/loid args) or this returns 403. Mixed listing: each item is a post or a comment, tagged kind. Requires calling POST /api/reddit/login on the REST API first to get session cookies (not an MCP tool). Example: name='spez' (must match the logged-in account).

List the posts and comments a Reddit account has HIDDEN. PRIVATE data -- Reddit only serves it to the account that owns it, so you must be logged in as name (see the reddit_session/loid args) or this returns 403. Mixed listing: each item is a post or a comment, tagged kind. Requires calling POST /api/reddit/login on the REST API first to get session cookies (not an MCP tool). Example: name='spez' (must match the logged-in account).

Fetch a Reddit user's public profile by username. Returns account info: username, id, karma (post + comment), account age, verified/employee flags, and avatar. Use to vet or summarize a redditor. Example: name='spez'.

List the posts and comments a Reddit account has SAVED. PRIVATE data -- Reddit only serves it to the account that owns it, so you must be logged in as name (see the reddit_session/loid args) or this returns 403. Mixed listing: each item is a post or a comment, tagged kind. Requires calling POST /api/reddit/login on the REST API first to get session cookies (not an MCP tool). Example: name='spez' (must match the logged-in account).

List a Reddit user's submitted POSTS (their post history, the sibling of reddit_user_comments). Returns posts with title, author, score, comment count, and permalink, plus an after cursor. Use to see what a redditor posts, not just what they comment on. Example: name='spez' sort='top'.

List the posts and comments a Reddit account has UPVOTED. PRIVATE data -- Reddit only serves it to the account that owns it, so you must be logged in as name (see the reddit_session/loid args) or this returns 403. Mixed listing: each item is a post or a comment, tagged kind. Requires calling POST /api/reddit/login on the REST API first to get session cookies (not an MCP tool). Example: name='spez' (must match the logged-in account).

Check whether specific Reddit comments still EXIST and are publicly visible, in one batch of up to 100 ids. A READ despite being a POST (ids travel in the body because a hundred of them do not fit in a URL); it costs the same as any other read and changes nothing on Reddit. Use it to tell 'deleted by the author' from 'removed by a moderator' from 'still there', which a normal comment fetch cannot distinguish, and to re-check a list of comments you posted or collected earlier. Accepts bare ids and t1_-prefixed fullnames interchangeably. Returns one row per id, in the order you sent them, each with a status. Example: ids=['n5abcde','t1_n5fghij'].