Skip to main content
Track Reddit posts and comments containing specific keywords with the same filtering primitives as keyword watchlists. Useful for monitoring subreddit conversations, indie-hacker chatter, support requests, and competitor mentions across Reddit.
Platform: Reddit. This endpoint creates Reddit watchlists only. To track the same keywords or prompt on LinkedIn, make a separate call to POST /api-keyword-watchlist (identical body shape). One watchlist = one platform; “LinkedIn and Reddit” always means two create calls. See Choose a watchlist type.
The endpoint accepts two body shapes. Pass either keywords (direct mode, documented below) or prompt (AI mode, documented in Prompt mode at the bottom of this page), not both.
Extension requirement. Collection runs through the OutX Chrome extension: at least one team member must have it installed and active, otherwise API requests return 403 Plugin installation required.
Start with Prompt mode. You send one sentence and OutX writes the keywords, the intent labels and the relevance objective. Keywords mode, documented first below, is the advanced path for callers that already know the exact strings to match. Before creating several watchlists, read Design your watchlists: one watchlist carries one signal.

​
Request Body (direct keywords mode)

​
string
Watchlist name. If not provided, a name will be auto-generated based on keywords.
​
array
required
Array of keywords to track on Reddit. Can be simple strings or advanced keyword objects with filtering rules.Simple format:
Advanced format with filters:
​
string
Optional description for the watchlist
​
array
Custom intent labels used to classify matching posts. Same shape as keyword watchlists: each label is a name, a description (what the AI matches a post against), and an optional default flag marking it as a pre-applied feed filter (at most 2 can be true; if you set the flag on some labels but mark none true, the first is promoted). If omitted, OutX generates a label taxonomy in the background. See Intent labels & defaults.
​
string
One-sentence objective describing who or what you want to find and why. It seeds the relevance-scoring vector, so it is what makes the feed rank and filter like a prompt-built watchlist.Optional but strongly recommended in keywords mode. If you omit it, OutX writes one in the background from the name, description and keywords, which is a guess at what your keyword strings were for. The response’s generated.objective tells you when that happened.
​
number
default:"24"
Fetch frequency in hours. Allowed values: 1, 3, 6, 12, 24, 48, 72. Reddit watchlists default to 24 (less frequent than LinkedIn since Reddit threads update more slowly).
​
string | null
Optional Slack incoming-webhook URL to receive a notification when new matching posts are found. Pass null to leave it unset.
​
string
Optional retry key you choose, up to 128 characters. A second create carrying the same key within about two minutes returns the watchlist the first one made instead of a duplicate. Send one on every create. See Idempotency.

​
Advanced Keyword Filtering

Each keyword can have additional filtering rules:
​
string
required
The primary keyword to search for in Reddit posts and comments
​
array
Optional, despite the name. Context keywords used together with the primary keyword. How they combine is controlled by include_all_required. Omit it, or send an empty array, to match on the primary keyword alone. Only keyword is required on a keyword object.
​
array
None of these keywords should be present in the post (NOT logic)
​
boolean
default:"true"
Controls how required_keywords combine. true (default) means every required keyword must be present (AND logic). false means any one is enough (OR logic). OR usually matches far more posts and is what the AI prompt generator uses, so set include_all_required to false when a multi-term required list is matching almost nothing. Plain-string keyword entries always use the default (AND).

​
Idempotency

Identical to the keyword watchlist contract, scoped to Reddit watchlists. In short:
  • Send idempotency_key. A second create with the same key, from the same team, within about two minutes is answered with the watchlist the first one made: 201 with created: false and deduplicated: true. The guard is best effort, not atomic, so retry one at a time rather than in parallel.
  • Without a key, a keywords-mode create is idempotent on the keyword set. A Reddit watchlist whose primary keywords match exactly (order-insensitive, lower-cased, trimmed) is returned with 200 OK, created: false, and its own fetchFreqInHours and labels.
Both guards run before the plan-watchlist check, so a retry that matches gets the existing watchlist back rather than a 402. A retry that does not match falls through to a normal create, plan check included.

​
Response Fields

​
string
Unique identifier for the watchlist
​
string
Watchlist name
​
string
URL-friendly slug for the watchlist
​
string
Always “reddit” for Reddit watchlists
​
array
Array of tracked keywords, normalized to lowercase and trimmed (e.g. "CompetitorName" is returned as "competitorname").
​
number
Fetch frequency in hours
​
boolean
true when a new watchlist was created, false when an existing watchlist was returned instead. See Idempotency.
​
boolean
Present and true only when a duplicate guard returned an existing watchlist. Absent on a normal create.
​
array
Array of keyword creation results
​
array
Intent labels persisted on the watchlist, as { key, description, default } objects. When you did not supply real labels, these are keyword-derived placeholders that are replaced by an AI-generated taxonomy a few seconds later (see message).
​
object
Keywords mode only. Two booleans, objective and labels, each true when you left that field out and OutX is writing it for you in the background. A generated label set gets at most two defaults, the same cap as a set you supply.generated.objective: true means the relevance target was inferred from your keyword strings rather than stated by you.
​
string
Present when OutX is generating a missing objective or label taxonomy in the background: "Watchlist created. An objective and intent labels are being generated in the background and will be available shortly."

​
Error Responses

​
Use Cases

Catch threads where people ask for tool recommendations:
Watch for Reddit posts that name a competitor:
Surface posts in indie-hacker spaces:

​
Prompt mode

Skip the keyword brainstorming and let OutX generate keywords and intent labels for you. Send a single prompt field describing what you want to track in plain English. OutX creates the watchlist immediately and runs keyword and label generation in the background.

​
Request Body

​
string
required
Plain-English description of what to track on Reddit. URLs are allowed; OutX fetches page metadata to improve keyword quality.Examples:
  • "Self-hosted CRM tools and competitors like NocoCRM, EspoCRM, Twenty"
  • "People asking for indie-friendly database hosting"
  • "Mentions of our product Acme on r/SaaS, r/indiehackers"
​
string
Optional watchlist name. Auto-generated from the prompt if omitted.
​
number
default:"24"
Fetch frequency in hours. Allowed values: 1, 3, 6, 12, 24, 48, 72.
​
string
Optional retry key you choose, up to 128 characters. Answered before the prompt is even read, so a retry costs nothing. See Idempotency.
​
boolean
default:"false"
When true, refuse to create rather than infer. Any slot OutX had to fill in itself triggers the refusal: topic, audience and signals whenever the prompt leaves them empty, and competitors, use_case or excluded whenever OutX inferred them. The call returns 422 with missing listing exactly which ones, and nothing is created.
Prompt mode reads only these five fields. labels, objective, description and slack_webhook_url are ignored on a prompt-mode create. OutX writes the objective itself, from the prompt.Of the other three, only labels and slack_webhook_url can be set afterwards with a PUT. objective and description are accepted on a keywords-mode create only. Update accepts neither, so a prompt-built watchlist cannot be given a hand-written objective or description through the API.
Keywords and intent labels populate on the watchlist a few seconds after creation. Use Get Reddit Watchlist to fetch the latest state. interpretation shows how the prompt was read into slots (topic, audience, signals, competitors, use case, exclusions, and a one-sentence refined_prompt), and assumed lists the slots OutX filled in by inference. A prompt that cannot produce a usable feed is refused with 422 and nothing is created; when the refusal body carries a question, relay it to your user word for word and retry with their answer. Full contract: When a prompt is refused.

​
Frequently Asked Questions

Both share the same keyword and label primitives. The difference is the source: keyword watchlists scan LinkedIn posts, Reddit watchlists scan Reddit posts and comments. The default fetch frequency is also less frequent (every 24h vs 12h for keyword watchlists) since Reddit threads update on a slower cadence.
Today, Reddit watchlists are keyword-driven and search across Reddit, not scoped to a subreddit list. To bias toward a subreddit, mention it in your prompt ("Track posts in r/SaaS about ...") so the AI keyword generator picks up subreddit-specific vocabulary.
Tracking begins immediately after creation. OutX scans Reddit on the next fetch cycle, based on the fetchFreqInHours value you set. Default is 24 hours.
When you reach the maximum number of watchlists allowed by your plan (across keyword, people, company, and reddit types combined), the API returns 402. You can either delete an existing watchlist to free up a slot, or upgrade your plan for higher limits.