reddit_monitor_add
Create a Reddit monitor that watches subreddits or all of Reddit for new posts or comments matching filters and sends matches to your webhooks.
Instructions
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.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Free-text keyword or phrase to match. Matched against the fields in `search_in` (default title+body+url). Omit to match every new post in the watched subreddits. | |
| kind | No | What to watch in the named subreddits: 'post' (default when omitted), 'comment', or 'both'. Comment monitoring requires a Growth, Pro or Scale plan -- on a lower tier this returns `comment_monitoring_requires_higher_tier` (402). Comments run roughly 7x the volume of posts, so expect proportionally more deliveries and check reddit_monitor_health's delivery ceiling before enabling it on a busy subreddit. | |
| nsfw | No | Set false to EXCLUDE NSFW/over-18 posts. Omitted or true both mean NSFW is allowed through -- there is no exclude-by-default; you must explicitly pass false to filter it out. POSTS ONLY: nsfw=false is REJECTED with a field-level 400 when kind is 'comment' or 'both', because Reddit flags NSFW on a post and never on an individual comment, so there is no field to filter a comment on. Run a kind='post' monitor to keep NSFW filtering, and cut unwanted comment text with exclude_terms. | |
| group | No | Optional label to bundle multiple matches into one delivery instead of one webhook call per match. Omit for one delivery per matching item. | |
| author | No | Only match posts by this Reddit username (without u/). | |
| domain | No | Outbound link domains to watch for (e.g. ['example.com']). Matches the post's link URL, any URL inside a self-post/comment body, and a crosspost's original link, including one that only appeared in the original post's body. Exact-or-subdomain match only: 'example.com' matches 'blog.example.com' but never 'notexample.com'. Does NOT resolve shortened links (bit.ly, t.co). | |
| cadence_s | No | Requested poll interval in seconds. May only be SLOWER than the plan tier's floor, never faster -- a too-low value is silently clamped up to the tier's minimum. Omit to use the tier's default. | |
| min_score | No | Only match posts with at least this many upvotes. | |
| search_in | No | Which fields keyword/term matching is scoped to. Default ['title', 'body', 'url']. Narrow to avoid false positives, e.g. a term that only appears in a URL slug matching a post that never mentions it in prose. All four resolve on comments as well as posts: on a comment, 'title' matches the title of the THREAD the comment sits under (a comment has no title of its own), which also applies through the default scope and can deliver every comment under a busy matching thread. Scope to ['body'] if you only want comments that say the term themselves. | |
| subreddit | No | Subreddits to watch, without the r/ prefix (e.g. ['SaaS', 'startups']). 1 to 50. OMIT this entirely (and set `q`) to watch ALL of Reddit for a keyword -- a monitor must be anchored by either a subreddit list or a keyword, never neither. Do NOT pass ['all']: r/all is Reddit's site-wide listing rather than a subreddit, so it is refused with 400 subreddit_reserved. Sitewide monitors are capped per plan tier (see reddit_monitor_list's `slots`) and cover POSTS only. | |
| include_all | No | EVERY one of these terms must appear (AND match) for the post to qualify, on top of any `q`. | |
| include_any | No | At least ONE of these terms must appear (OR match) for the post to qualify, on top of any `q`. | |
| webhook_ids | No | Restrict delivery to specific webhook(s) instead of every active webhook on the account. Pass id(s) from reddit_monitor_webhook_create/reddit_monitor_webhook_list. Omit (or pass an empty array) for the default: deliver to every active webhook you've registered. Every id must be a webhook you own -- returns `webhook_not_found` (400) otherwise. | |
| exclude_terms | No | Posts containing any of these terms are suppressed even if they otherwise match. Use to cut noise (e.g. exclude 'giveaway' from a brand-mention monitor). | |
| min_relevance | No | AI relevance floor, 0-100. 0 (the default) is off. Above 0, every match is scored by a language model against this monitor's own keywords and anything below the floor is NOT delivered -- it is recorded in your delivery history with status 'suppressed' and reason 'low_relevance', carrying its score and a one-line explanation, so you can always read what was filtered and why. Nothing is silently discarded. Rough calibration: 80-100 squarely on topic, 50-79 related but peripheral, 20-49 tangential, 0-19 the keyword is used in an unrelated sense. The comparison is inclusive, so a score equal to the floor is delivered. If scoring is unavailable the match is delivered UNSCORED rather than withheld. Requires a Growth, Pro or Scale plan -- on a lower tier this returns `ai_relevance_requires_higher_tier` (402). REJECTED with a field-level 400 on a monitor that has no q, include_any or include_all, because there would be no topic to score an item against and the floor could only ever admit everything. | |
| baseline_item_id | No | A Reddit post fullname (e.g. 't3_abc123') to use as the starting point instead of 'now' -- matching starts strictly after this item. Omit to start from the moment of creation. | |
| exclude_subreddits | No | Subreddits to SUPPRESS, without the r/ prefix (e.g. ['politics', 'AskReddit']). SITEWIDE MONITORS ONLY: pass this only when you have OMITTED `subreddit` and anchored the monitor with `q`. Passing it together with `subreddit` is rejected with a field-level 400 -- a monitor that names its subreddits should drop the unwanted name from that list instead. Up to 50, matched exactly like `subreddit` so 'r/Politics', '/r/politics' and 'politics' are one entry. This is the noise control for an all-of-Reddit keyword watch: it filters DELIVERY only, so it never changes what is polled, never frees quota, and never affects matching in any other subreddit. Independent of exclude_terms -- an item is dropped if either fires. |