Coverage
A search on Reddit polls posts, comments, or both: one mode per search, chosen withtypes. The criteria below are Reddit’s own, so they go in the search’s overrides.filters on the keyword (see Keywords).
In
posts mode a search 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 to 86400 seconds. At most 20 active Reddit searches 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 search reads 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 search carries, because nothing upstream did any searching. A term nothing said recently therefore finds nothing recently. Leave query out and the search 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 search 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 keyword says so in its activity, readable through GET /v1/keywords/{id}/activity. Lower the Source’s refreshIntervalSeconds when you see it: an active subreddit or a busy term wants 60–120 seconds, a quiet one is fine at 900.
History is shallow on a subreddit, deeper site-wide. A subreddit listing stops at about a thousand items, so it reaches back hours rather than weeks on a busy subreddit. The site-wide search pages back as far as the term goes. See Day-one backfill for what backfill: true reads when the keyword is created.
NSFW
NSFW posts are included by default. SetincludeNsfw: false on the search 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 search, 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 searches 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 searches 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.
A first scan reads both halves. A keyword created with backfill: true reads each listing, and the scan is billed for the requests it actually makes: 8 when both halves are read, like any other tick in this mode.
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 search establishes a silent baseline and emits nothing.
webhookUrl is optional: without it the keyword still records every match, readable through GET /v1/keywords/{id}/events in the same shape. See Webhooks.
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 keyword 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 keyword reports the failure in its activity rather than silently going quiet, readable throughGET /v1/keywords/{id}/activity.