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
| Field | Type | Meaning |
|---|---|---|
subreddit | string[] | Names without r/. Required unless you set a keyword q for sitewide monitoring: a monitor must be anchored by one or the other. |
exclude_subreddits | string[] | Subreddits to suppress. Sitewide monitors only (see below). |
kind | post | comment | both | Defaults to post. comment and both need Growth or above. |
q | string | A keyword or exact phrase, case-insensitive, matched on whole words. |
include_any | string[] | Matches if any term is present. |
include_all | string[] | Matches only if every term is present. |
exclude_terms | string[] | Drops the item if any term is present, as a whole-word phrase. Applied last. |
match | phrase | all_words | Defaults 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_words | boolean | true (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. |
stem | boolean | Defaults to false. true also matches simple English forms of each word: launch matches launches, launched and launching, and company matches companies. |
search_in | string[] | 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_since | object | Set by us, never by you: when this monitor started watching each subreddit stream. Anything you send is replaced. See "New items only" below. |
domain | string[] | Matches links to these domains. |
author | string | Exact author match. |
min_score | integer | Drops items scoring below this. |
min_relevance | integer | AI relevance floor, 0-100. 0 (the default) is off. Needs Growth or above, and needs at least one keyword field (see below). |
nsfw | boolean | false 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.
apimatches "our API is live" and "api-first", and does not matchtherapist,rapidorapis. A word boundary is only needed where your term starts or ends with a letter or digit, soc++matches "c++," andnode.jsmatches "(node.js)". Letters in any script count as word characters. - A term with several words is an exact phrase by default.
machine learningmatches "Machine learning" and "machine\n learning" (any spacing or line break between the words), and does not match "learning machine". Setmatch: "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,launchdoes not matchlaunches. List the forms you want, or setstem: truefor simple plural,-edand-ingforms. Stemming is English only and deliberately simple: it does not know irregular forms such asran. search_inscopes 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: addurlto 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), orpermalinkto match the thread path.exclude_termswins. An item matching bothinclude_anyandexclude_termsis dropped.exclude_subredditsis 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 fromsubredditinstead. Names are matched the same way as insubreddit:r/Politics,/r/politicsandpoliticsare one entry, up to 50 of them.exclude_subredditsis 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 ofexclude_terms: an item is dropped if either one fires, and neither substitutes for the other.domainmatches the host exactly or as a dot-suffix.example.commatchesexample.comandblog.example.com, and does not matchnotexample.com. Shortened links are not resolved: at.colink to your site matchest.co, not your domain.min_scoreis evaluated at detection time. A post found seconds after it was created has a score near zero, so amin_scoreabove 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,
titlemeans the THREAD's title. A Reddit comment has no title of its own, so asearch_inof["title"]on a comment matches against the title of the post the comment sits under. That also applies when you omitsearch_in, becausetitleis 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: falseis 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"andkind: "both"rejectnsfw: falseat creation. Keep NSFW filtering by running akind: "post"monitor, and filter comment text withexclude_terms.permalinkandurldiffer on a comment.permalinkis the comment's own path;urlis that path as a full reddit.com URL, and on a link post it is the outbound destination instead. Scope topermalinkto 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
suppressedand reasonlow_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, throughreddit_monitor_deliverieswithstatus: "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_relevanceabove0is rejected on a monitor with noq,include_anyorinclude_all, for the same reasonnsfw: falseis 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.
| Value | Meaning |
|---|---|
scored | The item was scored. enrichment.ai_relevance holds the score and reason. |
cap_reached | Your account used its monthly AI allowance. Delivered unscored. |
off | Your plan does not include AI relevance. Delivered unscored. |
unscored | Scoring 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.
