Create Keyword Watchlist

Create a keyword watchlist by specifying keywords directly or by describing what to track in plain English.

Track LinkedIn posts containing specific keywords with powerful filtering options. Monitor industry trends, job postings, or any topic of interest with customizable fetch frequencies.

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.

Request Body (direct keywords mode)

name · string

Watchlist name. If not provided, a name will be auto-generated based on keywords.

keywords · array · required

Array of keywords to track. Can be simple strings or advanced keyword objects with filtering rules.

Simple format:

["hiring", "blockchain", "remote work"]

Advanced format with filters:

[
  {
    "keyword": "software engineer",
    "required_keywords": ["remote", "senior"],
    "excluded_keywords": ["unpaid", "intern"]
  }
]

description · string

Optional description for the watchlist

labels · array

Custom labels for organization

[
  {
    "name": "hiring",
    "description": "Job postings"
  }
]

fetchFreqInHours · number · default: "12"

Fetch frequency in hours. Allowed values: 1, 3, 6, 12, 24, 48, 72

Advanced Keyword Filtering

Each keyword can have additional filtering rules:

keyword · string · required

The primary keyword to search for

required_keywords · array

All of these keywords must be present in the post (AND logic)

excluded_keywords · array

None of these keywords should be present in the post (NOT logic)

cURL

curl -X POST \
  "https://api.outx.ai/api-keyword-watchlist" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "name": "Remote Senior Jobs",
    "keywords": [
      {
        "keyword": "hiring",
        "required_keywords": ["remote", "senior", "engineer"],
        "excluded_keywords": ["unpaid", "intern"]
      },
      {
        "keyword": "job opening",
        "required_keywords": ["work from home"],
        "excluded_keywords": ["junior"]
      }
    ],
    "description": "Track remote senior engineering positions",
    "labels": [
      {
        "name": "hiring",
        "description": "Job postings"
      }
    ],
    "fetchFreqInHours": 6
  }'

Response (201 Created)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Remote Senior Jobs",
  "slug": "remote-senior-jobs-550e8400",
  "type": "keyword",
  "keywords": ["hiring", "job opening"],
  "fetchFreqInHours": 6,
  "created": true,
  "results": [
    {
      "success": true,
      "keyword": "hiring",
      "keyword_id": "660e8400-e29b-41d4-a716-446655440001"
    }
  ]
}

Idempotency

POST is idempotent on the keyword set. If your team already has a keyword 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

id · string

Unique identifier for the watchlist

name · string

Watchlist name

slug · string

URL-friendly slug for the watchlist

type · string

Always “keyword” for keyword watchlists

keywords · array

Array of tracked keywords

fetchFreqInHours · number

Fetch frequency in hours

created · boolean

true when a new watchlist was created (status 201), false when an existing watchlist with the same keyword set was returned (status 200).

results · array

Array of keyword creation results

Error Responses

Status Code	Error Message	Description
400	Missing required parameter: keywords	Keywords array is required
400	Invalid fetchFreqInHours value	Fetch frequency must be one of: 1, 3, 6, 12, 24, 48, 72
401	Unauthorized	Invalid or missing API key

Use Cases

Track Job Postings

Monitor hiring posts for specific roles and locations:

{
  "name": "Remote Engineering Jobs",
  "keywords": [
    {
      "keyword": "hiring",
      "required_keywords": ["engineer", "remote"],
      "excluded_keywords": ["intern", "junior"]
    }
  ]
}

Monitor Industry Trends

Track discussions about emerging technologies:

{
  "name": "AI Trends",
  "keywords": ["GPT-4", "Claude", "LLM", "artificial intelligence"],
  "fetchFreqInHours": 3
}

Competitor Analysis

Watch for mentions of competitors:

{
  "name": "Competitor Mentions",
  "keywords": [
    {
      "keyword": "CompetitorName",
      "excluded_keywords": ["partnership", "collaboration"]
    }
  ]
}

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

prompt · string · required

Plain-English description of what to track. URLs are allowed; OutX fetches page metadata to improve keyword quality.

Examples:

• "AI-native CRM tools and competitors like Salesforce, HubSpot"
• "People looking for remote software engineering jobs"
• "Mentions of our product Acme and common complaints"

name · string

Optional watchlist name. Auto-generated from the prompt if omitted.

fetchFreqInHours · number · default: "12"

Fetch frequency in hours. Allowed values: 1, 3, 6, 12, 24, 48, 72.

cURL

curl -X POST \
  "https://api.outx.ai/api-keyword-watchlist" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "prompt": "Track discussions about AI-native CRM tools, including competitors like Salesforce and HubSpot",
    "name": "AI CRM Watchlist",
    "fetchFreqInHours": 12
  }'

201 Created

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "AI CRM Watchlist",
  "slug": "ai-crm-watchlist-550e8400",
  "type": "keyword",
  "fetchFreqInHours": 12,
  "prompt": "Track discussions about AI-native CRM tools, including competitors like Salesforce and HubSpot",
  "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 Keyword Watchlist to fetch the latest state.

Frequently Asked Questions

Is there a maximum number of keywords I can add to a single watchlist?

The number of keywords per watchlist depends on your subscription plan. Free plans have lower limits, while Growth, Expert, and Ultimate plans allow more keywords. If you hit your plan’s keyword limit, the API will return an error. Contact [e-mail] for details on plan-specific limits.

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

Tracking begins immediately after creation. OutX will start scanning LinkedIn for matching posts on the next fetch cycle, based on the fetchFreqInHours value you set. If you set fetchFreqInHours to 1, you can expect the first results within an hour.

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

When you reach the maximum number of watchlists allowed by your plan, the API will return an error when you try to create a new one. You can either delete an existing watchlist to free up a slot, or upgrade your plan for higher limits.