RedditapisRedditapis
Live Monitoring

Filters

The filter spec, field by field, with the matching rules stated exactly, so you can predict what a monitor will and will not match.

A monitor is a filter_spec. Every field is optional, except that a monitor must be anchored by either subreddit or a keyword q.

{
  "subreddit": ["SaaS", "startups"],
  "kind": "both",
  "q": "pricing",
  "include_any": ["api", "sdk"],
  "include_all": ["reddit", "data"],
  "exclude_terms": ["hiring", "job"],
  "search_in": ["title", "body"],
  "match": "phrase",
  "whole_words": true,
  "stem": false,
  "domain": ["example.com"],
  "author": "some_user",
  "min_score": 5,
  "min_relevance": 70,
  "nsfw": false
}

Fields

FieldTypeMeaning
subredditstring[]Names without r/. Required unless you set a keyword q for sitewide monitoring: a monitor must be anchored by one or the other.
exclude_subredditsstring[]Subreddits to suppress. Sitewide monitors only (see below).
kindpost | comment | bothDefaults to post. comment and both need Growth or above.
qstringA keyword or exact phrase, case-insensitive, matched on whole words.
include_anystring[]Matches if any term is present.
include_allstring[]Matches only if every term is present.
exclude_termsstring[]Drops the item if any term is present, as a whole-word phrase. Applied last.
matchphrase | all_wordsDefaults to phrase: the words of a term must appear together and in order. all_words: every word of the term must appear, in any order, anywhere in the searched text. Applies to q, include_any and include_all.
whole_wordsbooleantrue (the default for new monitors) matches terms only as whole words. false matches them anywhere inside other words. See "Monitors created before whole-word matching" below.
stembooleanDefaults to false. true also matches simple English forms of each word: launch matches launches, launched and launching, and company matches companies.
search_instring[]Which fields the text terms look at. Any of title, body, url, permalink. Defaults to ["title", "body"]. All four resolve on comments as well as posts.
stream_sinceobjectSet by us, never by you: when this monitor started watching each subreddit stream. Anything you send is replaced. See "New items only" below.
domainstring[]Matches links to these domains.
authorstringExact author match.
min_scoreintegerDrops items scoring below this.
min_relevanceintegerAI relevance floor, 0-100. 0 (the default) is off. Needs Growth or above, and needs at least one keyword field (see below).
nsfwbooleanfalse drops items flagged NSFW. Posts only. Rejected on kind: "comment" or "both" (see below).

Matching rules, stated exactly

These are the details that decide whether you get an alert, so they are spelled out rather than left to intuition:

  • Text matching is case-insensitive, on whole words. api matches "our API is live" and "api-first", and does not match therapist, rapid or apis. A word boundary is only needed where your term starts or ends with a letter or digit, so c++ matches "c++," and node.js matches "(node.js)". Letters in any script count as word characters.
  • A term with several words is an exact phrase by default. machine learning matches "Machine learning" and "machine\n learning" (any spacing or line break between the words), and does not match "learning machine". Set match: "all_words" to accept the words in any order and any position. A phrase never runs from the end of the title into the start of the body.
  • Stemming is off unless you turn it on. With stem: false, launch does not match launches. List the forms you want, or set stem: true for simple plural, -ed and -ing forms. Stemming is English only and deliberately simple: it does not know irregular forms such as ran.
  • search_in scopes every text field (q, include_any, include_all, exclude_terms). Omit it and your terms are searched in the title and body only. Links are not searched unless you ask: add url to match a link's host and path (never its query string or #fragment, and never a link to a Reddit thread, including a self post's own link), or permalink to match the thread path.
  • exclude_terms wins. An item matching both include_any and exclude_terms is dropped.
  • exclude_subreddits is for sitewide monitors, and is rejected on a scoped one. A sitewide monitor watches all of Reddit for your keyword (search-based), so the one thing it cannot otherwise say is "everywhere except there". That is what this field is for, and it is where the noise on a keyword monitor actually comes from. A monitor that already lists its subreddits has no use for it, so passing both is rejected at creation with a field-level error rather than accepted and quietly ignored. Remove the unwanted name from subreddit instead. Names are matched the same way as in subreddit: r/Politics, /r/politics and politics are one entry, up to 50 of them.
  • exclude_subreddits is a delivery filter, not a cost or coverage setting. Excluding a subreddit changes what reaches you, never what we poll, so it does not slow your monitor down, does not free up any quota, and cannot cause you to miss a match anywhere else. Exclusion is absolute and independent of exclude_terms: an item is dropped if either one fires, and neither substitutes for the other.
  • domain matches the host exactly or as a dot-suffix. example.com matches example.com and blog.example.com, and does not match notexample.com. Shortened links are not resolved: a t.co link to your site matches t.co, not your domain.
  • min_score is evaluated at detection time. A post found seconds after it was created has a score near zero, so a min_score above about 2 combined with a fast plan will silently drop nearly everything. Fast detection and score thresholds pull against each other by nature.
  • On a comment, title means the THREAD's title. A Reddit comment has no title of its own, so a search_in of ["title"] on a comment matches against the title of the post the comment sits under. That also applies when you omit search_in, because title is part of the default scope. It widens what you get: a busy thread whose title carries your term can deliver every comment under it, bounded by your per-monitor delivery ceiling. Scope to ["body"] if you only want comments that say the term themselves.
  • nsfw: false is rejected on a monitor that watches comments. Reddit flags NSFW on a post, never on an individual comment, so there is no field to filter a comment on. Rather than accept the setting and silently never apply it, kind: "comment" and kind: "both" reject nsfw: false at creation. Keep NSFW filtering by running a kind: "post" monitor, and filter comment text with exclude_terms.
  • permalink and url differ on a comment. permalink is the comment's own path; url is that path as a full reddit.com URL, and on a link post it is the outbound destination instead. Scope to permalink to match on the thread path.

Where a term matched, matched_spans

Every delivered item carries matched_spans, a list of where your terms were found, so a dashboard or digest can highlight them:

"matched_spans": [
  { "field": "title", "start": 33, "end": 47 },
  { "field": "text", "start": 94, "end": 108 }
]

field is the key of the item the text came from (title, text or selftext for a post body, body for a comment, link_title for a comment's thread title, and url, link_url or permalink when you search links). start and end are character offsets into that field, end exclusive, so item[field].slice(start, end) is the matched text in its original case. Excluded terms never produce a span. At most 50 spans are returned per item.

Monitors created before whole-word matching

Whole-word phrase matching over title and body is the default for every monitor created from October 2026 on. Monitors that already existed keep the matching they were created with: substring matching (so api still matches apis), with url in the default search scope. We did not switch them, because that would have quietly stopped matches you may rely on.

You can tell which kind a monitor is from its filter_spec: a new monitor has "whole_words": true (or false if you chose it). An older monitor has no whole_words field. To move an older monitor to whole-word matching, update it with "whole_words": true. An update that does not mention whole_words keeps the monitor's current setting.

Sitewide monitors match whole words. A monitor with no subreddit finds posts through Reddit search, and Reddit search matches whole words only. So on a sitewide monitor, substring matching (whole_words: false, or an older monitor without the field) applies only to posts that Reddit search returned for your keyword: api inside apis is matched only when search returns that post. To match a keyword inside longer words everywhere in a community, add those communities to subreddit: scoped monitors read every new post and keep substring matching.

New items only

A monitor delivers items created after it started watching, never a backlog. That holds when you change a monitor too: switching kind from post to both, or adding a subreddit, starts the new stream from the moment of the change, so you do not receive comments or posts written before it. We record that moment per stream in stream_since. Streams the monitor already watched keep their original start.

A baseline_item_id set at creation is where that stream starts: items after it are new to the monitor, even ones posted a little before you created it (the 6 hour freshness limit still applies). You can send a fullname (t3_ or t1_), a bare post id, or a Reddit post or comment URL; it is stored as the fullname. Any other value is refused with 400 invalid_baseline_item_id. Before October 21, 2026 such a value was stored as sent and the monitor skipped every item, so it delivered nothing.

A baseline_item_id set at creation speaks for one kind only: a t3_ id is a starting point for posts, a t1_ id for comments. Until October 20, 2026 a monitor with kind: "both" and a t3_ baseline delivered posts and no comments at all, because every comment was wrongly read as older than the baseline. That is fixed, so if you have such a monitor, new comments start arriving on it from that date. Comments written before the fix are not sent.

Monitors brought in by an import from another monitoring tool keep substring matching (no whole_words field), so each keyword matches what it matched before the move. Send "whole_words": true with the import, or update the monitor later, to use whole-word matching instead.

AI relevance, min_relevance

Keyword matching is a text test, and relevance is a meaning test. A monitor watching apple gets the fruit; one watching notion gets the ordinary noun. No combination of exclude_terms fixes that in general, because the same word is genuinely both things.

Set min_relevance to a number from 1 to 100 and every match is scored by a language model against your own keywords before it is delivered. Anything below your floor is not sent.

{ "q": "notion", "min_relevance": 70 }

A rough calibration: 80-100 squarely on topic, 50-79 related but peripheral, 20-49 only tangentially connected, 0-19 the word is being used in an unrelated sense, or the item is spam. Start around 50 and raise it if you are still getting noise. The comparison is inclusive, so a score exactly equal to your floor is delivered.

Four things worth knowing before you turn it on:

  • Nothing is dropped. It is bucketed. A match below your floor is written to your delivery history with status suppressed and reason low_relevance, carrying the score it got and one line of model reasoning explaining it. It does not reach your webhook, but you can always read what was filtered and why, through reddit_monitor_deliveries with status: "suppressed" or on the dashboard. A filter you cannot audit is a filter you cannot trust, and a floor set too high should look like a floor set too high rather than like the product going quiet.
  • It is off by default and changes nothing until you set it. Omit it, or set it to 0, and your monitor behaves exactly as it does today.
  • If scoring is unavailable, you get the match. A timeout, a provider outage, or any other scoring failure delivers the item unscored rather than withholding it. We would rather send you something you did not need than silently withhold something you did.
  • It needs something to score against. min_relevance above 0 is rejected on a monitor with no q, include_any or include_all, for the same reason nsfw: false is rejected on comment monitors: on a bare subreddit, author or domain watch there is no topic to compare an item to, so the setting could only ever admit everything. Rather than bill you for a filter that silently does nothing, the API refuses it and says which field to add.

Available on Growth and above. Each scored match is a real per-match cost on our side, which is why it sits with comment monitoring rather than being a free toggle on every plan.

Monthly AI allowance and ai_relevance_status

AI scoring is counted per account per calendar month (UTC). A plan can carry a monthly allowance of scored matches; the current plans have no fixed monthly allowance, and Free and Starter are never scored. When an account with an allowance has used it, matches keep arriving for the rest of the month, unscored, and are never held back by your floor. Each match is counted once: a retry or a resend of an item that was already scored does not use the allowance again, and a match that could not be scored does not use it at all.

On a monitor with min_relevance above 0, delivered items normally carry enrichment.ai_relevance_status. It can be missing for a short time, for example right after a service restart, before your plan has been looked up: treat a missing value as unscored.

ValueMeaning
scoredThe item was scored. enrichment.ai_relevance holds the score and reason.
cap_reachedYour account used its monthly AI allowance. Delivered unscored.
offYour plan does not include AI relevance. Delivered unscored.
unscoredScoring was tried and gave no score (the item was too short, or scoring was unavailable). Delivered.

Monitors without min_relevance do not carry the field, so their payload is unchanged.

Worked example

Watch two subreddits for people asking about Reddit data, ignoring job posts, and only where the text appears in the title or body:

{
  "subreddit": ["SaaS", "startups"],
  "kind": "both",
  "include_any": ["reddit api", "scrape reddit", "reddit data"],
  "exclude_terms": ["hiring", "job", "salary"],
  "search_in": ["title", "body"]
}

Watch all of Reddit for your brand name, minus the two subreddits that generate the noise:

{
  "q": "acme",
  "exclude_subreddits": ["politics", "AskReddit"],
  "search_in": ["title", "body"]
}

Validation

Invalid specs are rejected at creation with a field-level error rather than silently accepted and never matching. A monitor that matches nothing because of a typo is indistinguishable from a quiet week, which is why this fails loudly instead.

Independent third-party API for developers and researchers. Not affiliated with, endorsed by, or sponsored by Reddit, Inc.

On this page