Limits
Slot ceilings, the per-monitor daily delivery cap, retention windows, and exactly what happens to a monitor when a payment fails.
Every limit that can change what you receive is documented here. An undocumented limit is indistinguishable from a bug, and a customer who hits one with no way to find out will reasonably conclude the product is broken.
Slots and cadence
| Plan | Monitor slots | Distinct subreddits | All-of-Reddit watches | Detection | Comments |
|---|---|---|---|---|---|
| Free | 1 | none, all of Reddit only | 1 | ~60 sec | no |
| Lite | 5 | 10 | 1 | ~2 min | no |
| Starter | 15 | 10 | 1 | ~60 sec | no |
| Growth | 50 | 25 | 3 | ~60 sec (30 sec rolling out) | rolling out |
| Pro | 200 | 50 | 10 | ~60 sec (30 sec rolling out) | rolling out |
| Scale | 500 | 100 | 25 | ~60 sec (30 sec rolling out) | rolling out |
Lite is retired and can no longer be bought; new plans start at Starter.
There are three ceilings here and they bound each other rather than multiplying. Read the row across before you read any single number: on Growth, 30, 25 and 3 are three different quantities, not three descriptions of the same allowance.
A monitor slot is one monitor row, whatever it watches. A distinct subreddit is one named subreddit counted once across every monitor on the account, however many monitors name it. An all-of-Reddit watch is a monitor with no subreddit named, matching a keyword against the new posts Reddit's search returns for it. All-of-Reddit watches are search-based.
Each is metered on its own because each costs something different. One monitor may name up to 50 subreddits, so without the second column a Starter account could stand up 400 poll streams from 15 monitors, and each distinct subreddit is its own poll against a shared budget. All-of-Reddit watches are a different shape: they read Reddit's search for each keyword rather than a subreddit feed, so on a busy keyword they can return fewer posts than a named-subreddit watch. They cost search reads, delivery volume and matching work, which is why they are capped rather than unlimited. A monitor row on its own costs nothing, which is why the slot count is the loosest of the three.
Exceeding any of them returns 402, naming which one: monitor_slots_exhausted,
distinct_subreddit_limit_reached, or sitewide_slots_exhausted. Every one of
these caps, and how many monitors and distinct subreddits you are currently
using, is reported on /reddit/monitor/list, so you never have to guess where
you stand.
What you get for free
Every account gets one watch for free, with no card. It covers new posts matching one keyword anywhere on Reddit (search-based), checked about every 60 seconds, sent to your webhook, Slack or Discord, up to 10,000 alerts a day.
The free watch cannot name a subreddit. Watching a named subreddit is on the paid plans, because each named subreddit is its own poll. Asking for a subreddit on the free watch returns 402 and names the upgrade.
A second watch is also on the paid plans. Comment matches and 30 second checks are rolling out on Growth and up, and are listed as live once they measure on time.
A slot is a monitor, not a match and not a delivery. One monitor may name up to 50 subreddits; what bounds how many different subreddits you may watch is the distinct-subreddit column above, counted across the whole account, and what bounds how many of your monitors may skip the subreddit entirely is the all-of-Reddit column beside it. Creating a monitor beyond any of the three ceilings returns 402, and the error names which one.
Detection times are typical, not guaranteed. Reddit has no push stream, so everything here is poll-bound.
Per-monitor daily delivery ceiling
There are no per-match charges and no API credits spent, so match volume never moves your bill. There is a per-monitor daily delivery ceiling, it is enforced, and here is the number:
| Plan | Alerts per monitor per day |
|---|---|
| Free | 10,000 |
| Starter | 10,000 |
| Growth | 25,000 |
| Pro | 50,000 |
| Scale | 100,000 |
The count is per monitor, not per account, and it resets at midnight UTC. It exists for a reason worth being honest about.
A monitor on a very high-volume subreddit with kind: "both" and no filter can
match tens of thousands of items a day. Delivering all of them means a sustained
flood of outbound requests, from us, with our name on them, at your server. That
is a denial of service we would be committing on your behalf.
When the ceiling engages:
- Deliveries stop for that monitor for the rest of the day.
- Suppressed alerts are recorded as delivery rows with status
suppressed, counted intosuppressed_24hon/reddit/monitor/health, and readable individually on/reddit/monitor/deliveries?status=suppressedwith the same post content a delivered alert carries. - The counter resets daily.
A suppressed alert is visible as suppressed, which is the difference between a documented limit and a bug.
suppressed_24h counts more than the ceiling. The freshness gate, the
relevance floor and a missing or disabled webhook also withhold matches, and
those are recorded the same way, with payload.suppressed.reason =
stale_item, low_relevance or no_live_webhook instead of delivery_ceiling. Read
suppressed_breakdown on /reddit/monitor/health to split them, and read
ceiling_reached rather than suppressed_24h > 0 to answer "am I over my
limit" -- a stale withhold never sets that flag, because no limit rejected it.
See Endpoints.
suppressed_24h is a floor, not a total. We store up to 500 ceiling suppression
records per monitor per UTC day. The stored rows are a sample of what was held
back, not a ledger of every one: a monitor matching many times over its ceiling
would otherwise write hundreds of thousands of rows a day for alerts it is not
sending. Past the cap, suppression still stops deliveries and still resets at
midnight UTC, it just stops adding rows. The row that reaches the cap says so,
in its payload, at payload.suppressed.record_cap_reached. So a
suppressed_24h in the hundreds means "at least this many, and the real number
may be far larger", never "this is the total". Treat any monitor whose
suppressed_breakdown.ceiling is above zero as one whose ceiling is doing real
work. A monitor with suppressed_24h above zero and ceiling at zero has not
touched its limit at all: those are freshness withholds, and raising the ceiling
would not change them.
If you are hitting it, the fix is a narrower filter rather than a bigger plan. The ceiling is per monitor, not per plan.
For scale: the busiest monitor we have ever run in production peaked at 2,091 deliveries in a day, so the lowest number in the table above is roughly 4.8x that. That figure is context for sizing your own workload, not a suggestion that the ceiling is soft. It is checked on every delivery and a monitor that reaches it stops sending until the next UTC day.
Monthly alert allowance (a warning, never a cut-off)
Each plan also carries an account-wide monthly alert allowance, counted across
every monitor: Free 1,000, Starter 25,000, Growth 250,000, Pro 1,000,000 and
Scale 5,000,000. It never stops a delivery. We email you at 50, 80 and 100
percent, and keep delivering past it. Only the per-monitor daily ceiling above
stops anything. Withheld items (stale_item, low_relevance, delivery_ceiling)
do not count against the allowance.
Retention
Polled items are retained for 14 days by default and never more than 30. The window exists to deduplicate the poll stream, not to build an archive.
This is not a product limitation we would remove if asked. Reddit's terms require deleting data not needed for the approved use, and monitoring's approved use is detection, which needs days rather than years. If you need history, keep what we deliver on your side, or use the per-call API.
Rate limits on management calls
Management endpoints are rate limited in fixed 60-second windows, shared across all API keys on your account. Exceeding it returns 429. Delivery is unaffected: a management limit never delays an alert.
What happens when a payment fails
- A failed payment starts a 3-day grace period. Nothing changes during it: monitors keep running while you fix the card. That is the entire point.
- After grace, monitors pause. They are never deleted.
- Cancelling pauses at period end: not immediately. You keep what you paid for.
- Downgrading keeps your newest monitors active up to the new ceiling and pauses the rest. You are told which ones stopped.
Nothing in this system deletes a monitor for a billing reason. A monitor holds a filter you wrote by hand; pausing is reversible the moment you pay, and deleting is not reversible at all.
Concurrency
Deliveries to a single target are ordered. If your endpoint is slow, deliveries queue rather than fanning out and arriving out of order.
If the delivery queue is saturated, callers receive a 503 with Retry-After
rather than hanging. A request that waits forever is worse than one that fails
quickly, because it ties up a connection on both ends and tells you nothing.
Independent third-party API for developers and researchers. Not affiliated with, endorsed by, or sponsored by Reddit, Inc.
Endpoints
All eleven monitoring endpoints, with request shapes and what each one returns, from creating a monitor through reading its deliveries.
Capabilities not in the reference
Two endpoints are live and billed but deliberately absent from the API reference, because the underlying call has not been verified end to end against a real account. This page says which, and why.
