> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://gtm-tools.sh/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://gtm-tools.sh/_mcp/server. # Reddit Tools > 21 tools covering the full Reddit-engagement loop: search posts + subreddits, list hot/new/rising, check posting rules, evaluate users, save / follow / subscribe, manage custom feeds (multireddits), post and comment, vote, read the inbox, and DM via Reddit's chat system (Matrix-based). The Reddit category covers the full Reddit-engagement loop. 21 tools organized by workflow stage: discover relevant threads, evaluate posters before engaging, post + comment + vote, follow up on conversations, and organize subscriptions + custom feeds. Every write action, and every read that Reddit gates from cloud-datacenter IPs, runs through a logged-in session shared via the [browser extension](/extension), so the same identity (and karma) persists across calls. > **New to Reddit outreach?** Read the [Results Ranking Optimization guide](/results-ranking) first: it covers the should-I-reply gate, anti-spam rules, and the engagement style that doesn't get accounts shadowbanned. ## Tools | Tool | Credits | Description | | -------------------------------- | ------- | ----------------------------------------------------------------------------- | | **Account** | | | | `list_connected_reddit_accounts` | 0 | List connected Reddit accounts | | **Discover** | | | | `search_reddit_posts` | 2 | Search Reddit posts by keyword (optionally restricted to a subreddit) | | `list_subreddit_posts` | 1 | List posts from a subreddit (hot / new / top / rising / controversial / best) | | `search_reddit_subreddits` | 1 | Search subreddits by name or description | | `get_subreddit_about` | 1 | Get a subreddit's metadata + rules (compliance check before posting) | | **Evaluate** | | | | `get_reddit_post` | 1 | Get a Reddit post and its full comment tree | | `get_reddit_user` | 1 | Get a user's karma, account age, and verified flags (credibility check) | | `list_reddit_user_posts` | 1 | List a user's recent posts and/or comments | | **Engage** | | | | `create_reddit_comment` | 5 | Reply to a Reddit post or comment | | `create_reddit_post` | 5 | Submit a new post to a subreddit (text or link) | | `vote_reddit` | 1 | Upvote, downvote, or clear a vote on a post or comment | | `send_reddit_message` | 5 | Send a direct message to a Reddit user | | **Follow up** | | | | `follow_reddit_post` | 1 | Follow/unfollow a post for new-comment notifications (best-effort) | | `save_reddit_thing` | 1 | Save (or unsave) a post/comment to your engagement queue | | `list_reddit_saved` | 1 | List saved posts and comments | | `list_reddit_inbox` | 1 | Read DMs, comment replies, post replies, and mentions | | **Organize** | | | | `subscribe_reddit_subreddit` | 1 | Bulk subscribe/unsubscribe to subreddits | | `list_reddit_subscriptions` | 1 | List subreddits the connected account is subscribed to | | `list_reddit_custom_feeds` | 1 | List the connected account's custom feeds (multireddits) | | `list_reddit_custom_feed_posts` | 1 | List posts from a custom feed, merged across subreddits | | `create_reddit_custom_feed` | 5 | Create a custom feed (multireddit) from a list of subreddits | ## Sessions: the browser extension Write tools (`create_reddit_comment`, `create_reddit_post`, `vote_reddit`, `send_reddit_message`) and the personal read tool (`list_reddit_inbox`) need a logged-in Reddit session. `get_reddit_post` also routes through a pooled session: Reddit 403s unauthenticated reads from cloud-datacenter IPs even for fully public threads, so the tool uses any pooled bearer to route the read through `oauth.reddit.com` (authenticated reads work from any IP). The session is shared through the [GTM Tools browser extension](/extension): install it, press **Connect**, and stay logged into Reddit in that browser. The pool re-syncs the moment Reddit rotates the session token, so the bearer the tools use always tracks your live browser. `list_connected_reddit_accounts` shows which accounts are active in the workspace pool. Each row carries: * `reddit_username`: pass this to any write tool as `senderUsername` * `connected_by`: the teammate whose browser contributed the session * `last_synced`: when the cookies were last refreshed * `status`: `ready` (account is usable) or `stale` (cookies present but Reddit's `/api/me.json` doesn't recognize them; reopen reddit.com to refresh) ## Reading a thread `get_reddit_post` returns the post **and** the full comment tree in a single call. Reddit's `/comments/.json` endpoint does both at once, so we don't split it into a separate `list_reddit_post_comments` tool the way LinkedIn does. ```bash curl -X POST https://api.gtm-tools.sh/api/v0/get_reddit_post \ -H "Authorization: Bearer $GTM_TOOLS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"url": "https://www.reddit.com/r/SaaS/comments/1abcde/some_slug/"}' ``` The response shape: ```json { "status": "ok", "post": { "id": "1abcde", "title": "...", "author": "rlnerd", "subreddit": "SaaS", "body": "...", // selftext for text posts "url": "...", // external URL for link posts "permalink": "https://www.reddit.com/r/SaaS/comments/1abcde/some_slug/", "score": 42, "num_comments": 38, "created_utc": 1735000000, "over_18": false, "flair": null }, "comments": [ { "id": "abc123", "author": "u1", "body": "...", "score": 8, "created_utc": 1735000100, "url": "https://www.reddit.com/r/SaaS/comments/1abcde/some_slug/abc123/", "replies": [ /* recursive */ ], "more_replies": 5 // unloaded child replies, if Reddit truncated } ], "more_top_level": 0 // unloaded top-level comments, if any } ``` Each comment's `url` is a permalink ready to pass back to `create_reddit_comment` for a threaded reply. `more_replies` and `more_top_level` surface truncation when a thread is too deep / long for a single response: Reddit returns "more" placeholders rather than hiding them, and so do we. Accepted URL shapes for `get_reddit_post`: * `https://www.reddit.com/r//comments///` * `https://www.reddit.com/r//comments////` (comment URL, resolves to the same post) * `https://old.reddit.com/r//comments//` * `https://www.reddit.com/comments/` * `https://redd.it/` ## Posting and commenting `create_reddit_comment` works for **both** top-level replies on a post **and** threaded replies on a specific comment. The URL shape decides: | URL pattern | Resulting reply | | ---------------------------------------------------- | ---------------------------------------------------------- | | Post URL (`/comments///`) | Top-level comment on the post (`thing_id=t3_`) | | Comment URL (`/comments////`) | Threaded reply to that comment (`thing_id=t1_`) | ```bash # Top-level comment on a post curl -X POST https://api.gtm-tools.sh/api/v0/create_reddit_comment \ -H "Authorization: Bearer $GTM_TOOLS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "senderUsername": "arnaudjnn", "url": "https://www.reddit.com/r/SaaS/comments/1abcde/some_slug/", "body": "+1 on the multi-room point. That's the underrated bit." }' ``` `create_reddit_post` submits either a **text post** (`body`, Markdown supported) or a **link post** (`linkUrl`); provide exactly one. The `subreddit` field accepts `hermesagent`, `r/hermesagent`, or `/r/hermesagent` (the `r/` prefix is stripped). Optional flags: `nsfw`, `spoiler`, `sendReplies` (default `true`; Reddit DMs you when people reply). ```bash # Text post curl -X POST https://api.gtm-tools.sh/api/v0/create_reddit_post \ -H "Authorization: Bearer $GTM_TOOLS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "senderUsername": "arnaudjnn", "subreddit": "u_arnaudjnn", "title": "Shipped a new Reddit MCP", "body": "We just added 7 Reddit tools to gtm-tools. Markdown works here." }' # Link post curl -X POST https://api.gtm-tools.sh/api/v0/create_reddit_post \ -H "Authorization: Bearer $GTM_TOOLS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "senderUsername": "arnaudjnn", "subreddit": "SaaS", "title": "Reddit Chat is built on Matrix", "linkUrl": "https://gtm-tools.sh/reddit-tools" }' ``` To post to your own profile (Reddit treats user profiles as a special subreddit), use `u_` as the subreddit name. ## Voting `vote_reddit` takes a post or comment URL and a `direction`: | `direction` | Reddit's `dir` | Effect | | ----------- | -------------- | ----------------------- | | `up` | `1` | Upvote | | `down` | `-1` | Downvote | | `none` | `0` | Clear any existing vote | ```bash curl -X POST https://api.gtm-tools.sh/api/v0/vote_reddit \ -H "Authorization: Bearer $GTM_TOOLS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "senderUsername": "arnaudjnn", "url": "https://www.reddit.com/r/SaaS/comments/1abcde/some_slug/abc123/", "direction": "up" }' ``` Reddit silently returns `{}` on success; the tool surfaces `{status: "ok", thing_id, direction}` so you have something concrete to log against. ## Inbox `list_reddit_inbox` reads any of the 6 Reddit inbox tabs via a `filter` enum: | `filter` | Reddit endpoint | What it returns | | ----------------- | -------------------- | ----------------------------------------------------------- | | `all` (default) | `/message/inbox` | Everything: DMs + comment replies + post replies + mentions | | `unread` | `/message/unread` | Only unread items | | `messages` | `/message/messages` | DMs only (legacy PM thread items) | | `comment_replies` | `/message/comments` | Replies to your comments | | `post_replies` | `/message/selfreply` | Replies to your posts | | `mentions` | `/message/mentions` | Username mentions | Each item carries: | Field | Type | Notes | | ------------------ | ------- | ---------------------------------------------------------------------------- | | `id` | string | Fullname: `t4_` for DMs, `t1_` for comment-derived items | | `type` | enum | `message` / `comment_reply` / `post_reply` / `mention` | | `author` | string | Sender username | | `subject` | string? | DMs only | | `body` | string | Message body | | `created_utc` | number | Unix timestamp | | `unread` | boolean | Read state at fetch time | | `subreddit` | string? | Comment-derived items only | | `link_title` | string? | Comment-derived items only; the parent post's title | | `context_url` | string? | Permalink to the comment in-thread; pass to `create_reddit_comment` to reply | | `parent_id` | string? | DM thread parent | | `first_message_id` | string? | First message in a DM thread | ```bash # Read recent comment replies and mentions without marking them read curl -X POST https://api.gtm-tools.sh/api/v0/list_reddit_inbox \ -H "Authorization: Bearer $GTM_TOOLS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"username": "arnaudjnn", "filter": "comment_replies", "limit": 20}' ``` `markRead` defaults to `false` so an agent can peek without mutating state. Pass `markRead: true` to flip items to read on fetch. ## Outreach `send_reddit_message` sends a direct message that lands in the recipient's **"Chats"** tab. It works for every Reddit account, modern and legacy, because under the hood it targets Reddit's chat infrastructure (Matrix Client-Server API against `matrix.redditspace.com`) rather than the deprecated `/api/compose` PM endpoint, which newer accounts can't receive. | Parameter | Type | Required | Description | | ------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------- | | `senderUsername` | string | Yes | The connected Reddit account to send as (`reddit_username` from `list_connected_reddit_accounts`) | | `recipientUsername` | string | Yes | Reddit username of the recipient (with or without `u/` prefix) | | `message` | string | Yes | Message body in plain text (max 10000 chars; Reddit Chat does not render Markdown) | ```bash curl -X POST https://api.gtm-tools.sh/api/v0/send_reddit_message \ -H "Authorization: Bearer $GTM_TOOLS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "senderUsername": "arnaudjnn", "recipientUsername": "SienaCX", "message": "Hey, saw your post on agent gateways. Worth a 15-min chat?" }' ``` On success the tool returns `{status: "ok", event_id, room_id, recipient, recipient_matrix_id}`. If a DM room with the recipient already exists, the message lands there; otherwise the tool creates a direct room (preset `trusted_private_chat`) and registers it as a DM so Reddit's UI groups it correctly. > **Why Matrix?** Reddit migrated chat off Sendbird onto a Matrix homeserver at `matrix.redditspace.com`. The Reddit `token_v2` cookie *is* the Matrix access token; no separate login or token exchange. User IDs are `@t2_:reddit.com`. E2EE is off by default. This is why `send_reddit_message` works universally while the legacy PM system fails for the majority of modern accounts. ## Discover The discovery stage finds threads worth engaging with. Four tools cover keyword surveillance, subreddit shortlisting, daily monitoring, and the all-important compliance check. ```bash # Search for threads matching a query (workhorse; start most workflows here) curl -X POST https://api.gtm-tools.sh/api/v0/search_reddit_posts \ -H "Authorization: Bearer $GTM_TOOLS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"query":"signal vs matrix self-hosted","subreddit":"selfhosted","sort":"relevance","time_window":"month","limit":25}' # Daily monitoring scan: `rising` finds threads with momentum (good for being first to comment) curl -X POST https://api.gtm-tools.sh/api/v0/list_subreddit_posts \ -H "Authorization: Bearer $GTM_TOOLS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"subreddit":"selfhosted","sort":"rising","limit":25}' # Shortlist relevant subreddits before subscribing or monitoring curl -X POST https://api.gtm-tools.sh/api/v0/search_reddit_subreddits \ -H "Authorization: Bearer $GTM_TOOLS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"query":"agent automation","sort":"relevance","limit":10}' # **Compliance gate**: call this before posting in a new subreddit curl -X POST https://api.gtm-tools.sh/api/v0/get_subreddit_about \ -H "Authorization: Bearer $GTM_TOOLS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"subreddit":"selfhosted"}' # Returns: { about: {name, subscribers, allow_images, restrict_posting, ...}, # rules: [{name, description, applies_to: "all|link|comment", priority}] } ``` `get_subreddit_about` returns both the subreddit's metadata **and** its rules. Reddit playbooks unanimously flag rule-violations as the #1 shadowban trigger, and `create_reddit_post` and `create_reddit_comment` won't check rules for you; the agent has to. ## Evaluate Before engaging, confirm the poster is your ICP (not a bot, not a serial promoter). Two tools cover the credibility check + posting history. ```bash # Credibility check: karma, account age, verified email curl -X POST https://api.gtm-tools.sh/api/v0/get_reddit_user \ -H "Authorization: Bearer $GTM_TOOLS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"username":"rlnerd"}' # Posting history: which subreddits, what they talk about curl -X POST https://api.gtm-tools.sh/api/v0/list_reddit_user_posts \ -H "Authorization: Bearer $GTM_TOOLS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"username":"rlnerd","type":"overview","sort":"new","limit":25}' ``` **Red flags to filter out:** very young account (under 30 days) with disproportionately high karma; lopsided ratio of posts to comments (real users do both); posting concentrated in known promotional subs. ## Follow up After engaging, you want notifications and a queue. `save_reddit_thing` doubles as a CRM-style queue via the optional `category` label. ```bash # Follow a post for new-comment notifications curl -X POST https://api.gtm-tools.sh/api/v0/follow_reddit_post \ -H "Authorization: Bearer $GTM_TOOLS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"senderUsername":"arnaudjnn","url":"https://www.reddit.com/r/...","follow":true}' # Save a post with a CRM-stage category curl -X POST https://api.gtm-tools.sh/api/v0/save_reddit_thing \ -H "Authorization: Bearer $GTM_TOOLS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"senderUsername":"arnaudjnn","url":"https://www.reddit.com/r/...","action":"save","category":"p0-reply"}' # Read the engagement queue back curl -X POST https://api.gtm-tools.sh/api/v0/list_reddit_saved \ -H "Authorization: Bearer $GTM_TOOLS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"senderUsername":"arnaudjnn","limit":50}' ``` > **`follow_reddit_post` is best-effort.** Reddit's `/api/follow_post` endpoint is used by the mobile/web clients but isn't part of Reddit's documented API. The tool surfaces a clean error if Reddit returns 404; fall back to polling `get_reddit_post` on a schedule if that happens. ## Organize Custom feeds (Reddit calls them "multireddits") bundle multiple subreddits into a single stream: one feed per ICP / persona / monitoring theme, then `list_reddit_custom_feed_posts` reads the merged stream in one call. ```bash # Bulk-subscribe to your shortlist (also a credibility signal: moderators # check whether new accounts have organic subscriptions) curl -X POST https://api.gtm-tools.sh/api/v0/subscribe_reddit_subreddit \ -H "Authorization: Bearer $GTM_TOOLS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"senderUsername":"arnaudjnn","subreddits":["selfhosted","privacy","Matrix","HomeNetworking"],"action":"sub"}' # Audit current subscriptions curl -X POST https://api.gtm-tools.sh/api/v0/list_reddit_subscriptions \ -H "Authorization: Bearer $GTM_TOOLS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"senderUsername":"arnaudjnn","limit":100}' # Create a "self-hosted infra" monitoring feed curl -X POST https://api.gtm-tools.sh/api/v0/create_reddit_custom_feed \ -H "Authorization: Bearer $GTM_TOOLS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "senderUsername":"arnaudjnn", "name":"selfhost_infra", "subreddits":["selfhosted","homelab","HomeNetworking","privacy","Matrix"], "visibility":"private", "description":"Monitoring feed for self-hosted infra discussions" }' # Daily read: merged feed across all 5 subreddits in one call curl -X POST https://api.gtm-tools.sh/api/v0/list_reddit_custom_feed_posts \ -H "Authorization: Bearer $GTM_TOOLS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"senderUsername":"arnaudjnn","feed_name":"selfhost_infra","sort":"rising","limit":50}' ``` ## Next steps #### [LinkedIn Tools](/linkedin-tools) LinkedIn automation: the cross-platform counterpart to Reddit outreach. #### [Enrichment Tools](/enrichment-tools) Verify professional emails and resolve handles for prospects you find via Reddit. #### [Browser Extension](/extension) Install the extension and connect your Reddit session.