Coverage
A Watch on Reddit polls posts, comments, or both — one mode per Watch, chosen withtypes.
In
posts mode a Watch runs post search, or lists a subreddit’s newest posts when it carries no term. Post search accepts Reddit’s own query syntax in query — title:keyword, author:username, flair:text, self:yes, url:domain.com — and subreddit scopes it. A search can carry several terms at once, OR’d into one upstream request at one tick’s cost.
Interval: 60–86400 seconds. Cap: 20 active Watches per Account. Each tick costs 4 credits in posts and comments, and 8 credits in all, which reads two listings a tick.
Comments
Most of what people say about a product on Reddit, they say in a comment — not in a submission’s title.types: "comments" reads comments instead of posts: a subreddit’s newest comments when you name one, or the comments a term finds site-wide when you do not.
webdev+reactjs+nextjs, and cost one listing, one tick, one credit charge, exactly like a single one. Without a subreddit, the Watch searches comments site-wide by the term, newest first — the same search the “Comments” tab of Reddit’s own search bar runs. Neither alone is refused; both missing is, because there is no useful “every comment on Reddit”.
On a subreddit, a term filters; it does not search. A comment listing takes no query, so query (or terms) is matched on our side, over the page that came back — and it is applied whatever match mode the Watch carries, because nothing upstream did any searching. A term nothing said recently therefore finds nothing recently. Leave query out and the Watch reports every new comment in the subreddit.
Site-wide, the term searches, and is still matched on our side. Reddit’s comment search matches loosely — a search for stalkr also returns stalker — so the term is matched again over what came back, whatever match mode the Watch carries. Set match: "word" to tighten it further.
Each tick reads one page. On a subreddit that is 100 comments, Reddit’s maximum; site-wide it is the short page the search serves, about eight. If more comments arrive between two ticks than a page holds, the ones in the gap are missed — neither route has a window to reach back into. When a tick can prove it fell behind (a full page that shares nothing with the previous one), the Watch says so in its activity, readable through GET /v1/reddit/watches/{id}/activity. Lower refresh_interval_seconds when you see it: an active subreddit or a busy term wants 60–120 seconds, a quiet one is fine at 900.
Backfill is shallow on a subreddit, deeper site-wide. A Watch created with backfill: true sweeps backwards. A subreddit listing stops at about a thousand items — hours rather than weeks on a busy subreddit. The site-wide search pages back as far as the term goes, within the same sixty-day window as every other sweep.
NSFW
NSFW posts are included by default. Setinclude_nsfw: false on the Watch to filter them out. The isNsfw field is always present on post objects.
Posts and comments
types: "all" reads both halves of a subreddit in a single tick: its newest posts and its newest comments. One Watch, one webhook, one line in the sidebar, instead of two of each on the same subject.
all is billed at twice the rate of either half. Two separate Watches would cost the same 8 — this mode buys you one configuration and one feed, not a discount.
A subreddit or a term is required, for the same reason as in comments: the comments half is a subreddit listing when a subreddit is named, and the site-wide comment search by the term otherwise. The multi-subreddit syntax (webdev+reactjs) applies to both halves.
Each half keeps its own event type. A submission arrives as post.created, a comment as reddit_comment.created — exactly what two separate Watches would have delivered. all is a mode of polling, not a third kind of content.
The term is asymmetric, and worth understanding. On the posts half, query is sent to Reddit and matched by Reddit’s own index — with its stemming and its ranking. On the comments half there is nothing to send it to, so it is matched on our side over the page that came back. One match mode, two matching semantics. Set match: "word" to tighten both.
Backfill sweeps both halves. A Watch created with backfill: true walks each listing backwards on its own cursor, and each page is billed for the requests it actually makes — 8 while both halves still have pages, 4 once one runs out. The comments half runs out first, for the reason above.
What an event carries
A post is delivered as apost.created event with the full enriched post: title, body, author, subreddit, score and the link it submitted. A comment is delivered as reddit_comment.created, in the same post object, with kind: "comment":
The first tick of a Watch establishes a silent baseline and emits nothing.
webhook_url is optional — without it the Watch still records every match, readable through GET /v1/reddit/watches/{id}/events. See Webhooks.
The event feed is cursor-paginated: pass the opaque nextCursor back unchanged on the next request.
Ids
Post ids are normalised to a bare base36id plus a fullname (t3_…), whichever form Reddit used. A comment’s id is its full t1_… name, prefix included: Reddit numbers comments and posts on separate sequences, so a bare comment id can collide with a post id, and the prefix is what keeps two different items from counting as one.
Limits
A post removed or deleted after a Watch captured it keeps its recorded event — the feed is what we saw, at the time we saw it. A private or banned subreddit simply stops producing matches; the Watch reports the failure in its activity rather than silently going quiet, readable throughGET /v1/reddit/watches/{id}/activity.