Filters

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"],
  "domain": ["example.com"],
  "author": "some_user",
  "min_score": 5,
  "min_relevance": 70,
  "nsfw": false
}

Fields

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 substring: not word-boundary. api matches therapist. If that matters, use a longer term or add exclude_terms.
• search_in scopes every text field (q, include_any, include_all, exclude_terms). Omit it and the default scope is used; set it and only those fields are searched. A term that only appears in a URL will not match if search_in is ["title"].
• 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, 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.

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.

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.