Create Reddit Watchlist

curl -X POST \
  "https://api.outx.ai/api-reddit-watchlist" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "name": "Self-hosted CRM Threads",
    "keywords": [
      {
        "keyword": "crm",
        "required_keywords": ["self-hosted", "open source"],
        "excluded_keywords": ["salesforce", "enterprise"]
      },
      "indie hacker crm"
    ],
    "description": "Track Reddit threads about self-hosted CRM tools",
    "labels": [
      {
        "name": "buying intent",
        "description": "Threads asking for tool recommendations"
      }
    ],
    "fetchFreqInHours": 12
  }'

const response = await fetch("https://api.outx.ai/api-reddit-watchlist", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "YOUR_API_KEY",
  },
  body: JSON.stringify({
    name: "Self-hosted CRM Threads",
    keywords: [
      {
        keyword: "crm",
        required_keywords: ["self-hosted", "open source"],
        excluded_keywords: ["salesforce", "enterprise"],
      },
    ],
    fetchFreqInHours: 12,
  }),
});

const data = await response.json();

import requests

url = 'https://api.outx.ai/api-reddit-watchlist'
headers = {
    'Content-Type': 'application/json',
    'x-api-key': 'YOUR_API_KEY'
}
payload = {
    'name': 'Self-hosted CRM Threads',
    'keywords': [
        {
            'keyword': 'crm',
            'required_keywords': ['self-hosted', 'open source'],
            'excluded_keywords': ['salesforce', 'enterprise']
        }
    ],
    'fetchFreqInHours': 12
}

response = requests.post(url, headers=headers, json=payload)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Self-hosted CRM Threads",
  "slug": "self-hosted-crm-threads-550e8400",
  "type": "reddit",
  "keywords": ["crm", "indie hacker crm"],
  "fetchFreqInHours": 12,
  "created": true,
  "results": [
    {
      "success": true,
      "keyword": "crm",
      "keyword_id": "660e8400-e29b-41d4-a716-446655440001"
    }
  ],
  "labels": [
    { "key": "buying intent", "description": "Threads asking for tool recommendations", "default": true }
  ]
}

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Self-hosted CRM Threads",
  "slug": "self-hosted-crm-threads-550e8400",
  "type": "reddit",
  "keywords": ["crm", "indie hacker crm"],
  "fetchFreqInHours": 12,
  "created": false,
  "labels": [
    { "key": "buying intent" }
  ]
}

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.

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:

["self-hosted", "open source crm", "indie hacker"]

Advanced format with filters:

[
  {
    "keyword": "crm",
    "required_keywords": ["self-hosted", "open source"],
    "excluded_keywords": ["enterprise", "salesforce"],
    "include_all_required": false
  }
]

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.

[
  {
    "name": "buying intent",
    "description": "Threads asking for tool recommendations",
    "default": true
  }
]

string

Optional one-sentence objective describing who or what you want to find and why. It seeds the relevance-scoring vector so posts rank like a prompt-built watchlist. If omitted, OutX generates one in the background from the name, description, and keywords.

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.

Advanced Keyword Filtering

Each keyword can have additional filtering rules:

string

required

The primary keyword to search for in Reddit posts and comments

array

Context keywords used together with the primary keyword. How they combine is controlled by include_all_required.

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).

curl -X POST \
  "https://api.outx.ai/api-reddit-watchlist" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "name": "Self-hosted CRM Threads",
    "keywords": [
      {
        "keyword": "crm",
        "required_keywords": ["self-hosted", "open source"],
        "excluded_keywords": ["salesforce", "enterprise"]
      },
      "indie hacker crm"
    ],
    "description": "Track Reddit threads about self-hosted CRM tools",
    "labels": [
      {
        "name": "buying intent",
        "description": "Threads asking for tool recommendations"
      }
    ],
    "fetchFreqInHours": 12
  }'

const response = await fetch("https://api.outx.ai/api-reddit-watchlist", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "YOUR_API_KEY",
  },
  body: JSON.stringify({
    name: "Self-hosted CRM Threads",
    keywords: [
      {
        keyword: "crm",
        required_keywords: ["self-hosted", "open source"],
        excluded_keywords: ["salesforce", "enterprise"],
      },
    ],
    fetchFreqInHours: 12,
  }),
});

const data = await response.json();

import requests

url = 'https://api.outx.ai/api-reddit-watchlist'
headers = {
    'Content-Type': 'application/json',
    'x-api-key': 'YOUR_API_KEY'
}
payload = {
    'name': 'Self-hosted CRM Threads',
    'keywords': [
        {
            'keyword': 'crm',
            'required_keywords': ['self-hosted', 'open source'],
            'excluded_keywords': ['salesforce', 'enterprise']
        }
    ],
    'fetchFreqInHours': 12
}

response = requests.post(url, headers=headers, json=payload)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Self-hosted CRM Threads",
  "slug": "self-hosted-crm-threads-550e8400",
  "type": "reddit",
  "keywords": ["crm", "indie hacker crm"],
  "fetchFreqInHours": 12,
  "created": true,
  "results": [
    {
      "success": true,
      "keyword": "crm",
      "keyword_id": "660e8400-e29b-41d4-a716-446655440001"
    }
  ],
  "labels": [
    { "key": "buying intent", "description": "Threads asking for tool recommendations", "default": true }
  ]
}

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Self-hosted CRM Threads",
  "slug": "self-hosted-crm-threads-550e8400",
  "type": "reddit",
  "keywords": ["crm", "indie hacker crm"],
  "fetchFreqInHours": 12,
  "created": false,
  "labels": [
    { "key": "buying intent" }
  ]
}

Idempotency

POST is idempotent on the keyword set. If your team already has a Reddit watchlist whose primary keywords match the request exactly (order-insensitive, lower-cased, trimmed), the existing watchlist is returned with:

HTTP status 200 OK (instead of 201 Created)
created: false
The existing watchlist’s fetchFreqInHours and labels are returned, your request’s values are ignored for the duplicate match.

Use this to safely retry creations without hitting the plan-watchlist limit. The plan check is only applied when a brand-new watchlist would be created.

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 (status 201), false when an existing watchlist with the same keyword set was returned (status 200).

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).

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

Status Code	Error Message	Description
400	Either `keywords` array or `prompt` string is required	No keywords or prompt was supplied
400	Provide either `keywords` or `prompt`, not both	Both modes were supplied at once
400	Invalid fetchFreqInHours. Allowed values: 1, 3, 6, 12, 24, 48, 72 (hours)	Fetch frequency was not one of the allowed values
401	Missing API Key / Invalid API Key	Invalid or missing API key
402	Your plan includes up to N watchlists. Upgrade… or delete an existing watchlist to add a new one.	Watchlist quota for your plan reached (counts keyword, people, company, and reddit watchlists together)
403	Plugin installation required	No team member has had the OutX Chrome extension active in the last 48 hours.

Use Cases

Track Buying Intent on Subreddits

Catch threads where people ask for tool recommendations:

{
  "name": "CRM Buying Threads",
  "keywords": [
    {
      "keyword": "crm",
      "required_keywords": ["recommend", "looking for", "alternatives"]
    }
  ]
}

Monitor Competitor Mentions

Watch for Reddit posts that name a competitor:

{
  "name": "Competitor Mentions on Reddit",
  "keywords": [
    {
      "keyword": "CompetitorName",
      "excluded_keywords": ["partnership", "ad"]
    }
  ],
  "fetchFreqInHours": 12
}

Find Indie Hacker Discussions

Surface posts in indie-hacker spaces:

{
  "name": "Indie Hacker Reddit",
  "keywords": ["indie hacker", "side project", "bootstrapped saas"]
}

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.

curl -X POST \
  "https://api.outx.ai/api-reddit-watchlist" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "prompt": "Track Reddit threads about self-hosted CRMs and indie SaaS founders looking for alternatives to Salesforce",
    "name": "Self-hosted CRM Reddit",
    "fetchFreqInHours": 24
  }'

const response = await fetch("https://api.outx.ai/api-reddit-watchlist", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "YOUR_API_KEY",
  },
  body: JSON.stringify({
    prompt:
      "Track Reddit threads about self-hosted CRMs and indie SaaS founders looking for alternatives to Salesforce",
    fetchFreqInHours: 24,
  }),
});

const result = await response.json();
console.log("Watchlist created:", result.id);

import requests

headers = {
    "Content-Type": "application/json",
    "x-api-key": "YOUR_API_KEY",
}

payload = {
    "prompt": "Track Reddit threads about self-hosted CRMs and indie SaaS founders looking for alternatives to Salesforce",
    "fetchFreqInHours": 24,
}

response = requests.post(
    "https://api.outx.ai/api-reddit-watchlist",
    headers=headers,
    json=payload,
)

result = response.json()
print("Watchlist created:", result["id"])

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Self-hosted CRM Reddit",
  "slug": "self-hosted-crm-reddit-550e8400",
  "type": "reddit",
  "fetchFreqInHours": 24,
  "prompt": "Track Reddit threads about self-hosted CRMs and indie SaaS founders looking for alternatives to Salesforce",
  "created": true,
  "message": "Watchlist created. Keywords and labels are being generated in the background and will be available shortly."
}

Keywords and intent labels populate on the watchlist a few seconds after creation. Use Get Reddit Watchlist to fetch the latest state.

Frequently Asked Questions

How is a Reddit watchlist different from a keyword watchlist?

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.

Can I track specific subreddits?

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.

How soon does tracking start after I create a Reddit watchlist?

Tracking begins immediately after creation. OutX scans Reddit on the next fetch cycle, based on the fetchFreqInHours value you set. Default is 24 hours.

What happens when I hit my plan's watchlist limit?

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.

Getting Started

Authentication (OTP)

Keyword Watchlist

People Watchlist

Company Watchlist

Reddit Watchlist

Posts & Engagement

Team & Usage

LinkedIn Data

Integrations

Create Reddit Watchlist

Request Body (direct keywords mode)

Advanced Keyword Filtering

Idempotency

Response Fields

Error Responses

Use Cases

Prompt mode

Request Body

Frequently Asked Questions

​Request Body (direct keywords mode)

​Advanced Keyword Filtering

​Idempotency

​Response Fields

​Error Responses

​Use Cases

​Prompt mode

​Request Body

​Frequently Asked Questions

Request Body (direct keywords mode)

Advanced Keyword Filtering

Idempotency

Response Fields

Error Responses

Use Cases

Prompt mode

Request Body

Frequently Asked Questions