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,
  "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.

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.