---
title: "Create Monitor"
method: POST
path: "/api/reddit/monitor/add"
tags: ["Monitoring"]
---

# Create Monitor

`POST /api/reddit/monitor/add`

## Request

- Base URL: `https://api.redditapis.com`
- URL: `https://api.redditapis.com/api/reddit/monitor/add`
- Auth: HTTP bearer

Create a monitor: subreddits to watch, or all of Reddit at once, plus an optional filter. Forward-looking only from creation (or from baseline_item_id). Every account has a free entitlement of one all-of-Reddit post watch at a 60s cadence, so no subscription is needed to create that monitor; naming a subreddit requires a paid plan and returns 402 subreddit_scope_requires_paid_plan otherwise. Requires a free monitor slot. Two separate limits apply: monitor slots, and how many DISTINCT subreddits the plan covers across all your monitors (the same subreddit named in two monitors counts once, because it is one poll stream). Returns 402 subscription_required, monitor_slots_exhausted, sitewide_slots_exhausted or distinct_subreddit_limit_reached, 501 sitewide_comment_monitoring_not_available for a sitewide comment monitor, or 400 subreddit_not_found for an unknown subreddit. Cost: Free per call.

## Request body

- object
  - `filter_spec` object, required: What this monitor watches for. A monitor with only `subreddit` is legal and common ("everything in r/X"). A monitor must be anchored by either `subreddit` or a keyword `q`: omit `subreddit` and set `q` to watch all of Reddit.
    - `subreddit` string[]: Subreddits to watch, without the r/ prefix. 1-50. Omit entirely (and set q) to watch all of Reddit for a keyword.
    - `exclude_subreddits` string[]: Subreddits to suppress, without the r/ prefix. SITEWIDE MONITORS ONLY: rejected with a field-level 400 when subreddit is also set, because a monitor that names its subreddits should drop the unwanted name from that list instead. Matched the same way as subreddit (r/Politics, /r/politics and politics are one entry). A delivery filter, not a cost lever: it changes what reaches you, never what is polled.
    - `q` string: Free-text keyword or phrase, matched against the fields in search_in (default title+body+url).
    - `author` string: Only match posts by this Reddit username (without u/).
    - `exclude_terms` string[]: Posts containing any of these terms are suppressed even if they otherwise match.
    - `domain` string[]: Outbound link domains to watch for (e.g. example.com). Exact-or-subdomain match only; does not resolve shortened links.
    - `include_any` string[]: At least one of these terms must appear (OR match), on top of any q.
    - `include_all` string[]: Every one of these terms must appear (AND match), on top of any q.
    - `search_in` string[]: Which fields keyword/term matching is scoped to. Default [title, body, url].
    - `group` string: Optional label to bundle multiple matches into one delivery instead of one per match.
    - `min_score` integer: Only match posts with at least this many upvotes.
    - `nsfw` boolean: 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.
  - `cadence_s` integer: 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.
  - `baseline_item_id` string: A Reddit post fullname (e.g. t3_abc123) to start matching strictly after, instead of the moment of creation.

## Response `200`

Successful response.

- object

## Other responses

- `400`: Bad request — missing or invalid parameters.
- `401`: Missing Bearer token.
- `402`: The account holds no recognised monitoring entitlement (subscription_required), a free account named a subreddit, which is a paid capability (subreddit_scope_requires_paid_plan), the plan's monitor slot limit is already in use (monitor_slots_exhausted), the plan's separate all-of-Reddit watch cap is reached (sitewide_slots_exhausted), or the account already watches as many distinct subreddits as the plan covers (distinct_subreddit_limit_reached). Note that every account holds a free entitlement of one all-of-Reddit post watch, so an account with no subscription is not by itself a 402.
- `403`: Invalid Bearer token.
- `429`: Rate limit exceeded.
- `500`: Unexpected server error.
- `502`: Upstream (Reddit) rejected the request — cookies expired or account flagged.

---

[API](https://skmtc.dev/redditapis/apis/redditapis-api.md) · [All operations](https://skmtc.dev/redditapis/apis/redditapis-api/llms.txt) · [OpenAPI document](https://skmtc.dev/redditapis/apis/redditapis-api/revisions/9696482dfe9b?raw)