Skip to main content
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"],
    "include_all_required": false
  }
]
​
description
string
Optional description for the watchlist
​
labels
array
Custom intent labels OutX uses to classify matching posts. Each label is a name and a description; the description is what the AI matches a post against. See How intent labels are calculated.
[
  {
    "name": "hiring",
    "description": "Job postings"
  }
]
​
fetchFreqInHours
number
default:"12"
Fetch frequency in hours. Allowed values: 1, 3, 6, 12, 24, 48, 72

​
How intent labels are calculated

Labels (shown as Intents in the OutX app) are how OutX classifies the meaning of a matched post, not just whether it matched a keyword. Each label is a name plus a description, and the description is what the AI matches a post against. Labels are stored on the watchlist, not on individual posts. They are applied to posts during a background enrichment pass and then surface on each post in the Get posts response as tags (the matched label name) and tagDescriptions.
The same concept has two names in the API: labels on the watchlist, tags on a post. A post’s tag is the label it was classified into. A post with no confident match gets the tag "na".

​
How a post gets classified

Each newly collected post is enriched in two steps:
  1. Relevance scoring (deterministic). The post is scored against the watchlist using embedding similarity plus keyword matching, producing relevance_score (1-10). Low-relevance posts are tagged "na" and skip the next step.
  2. Label selection (AI). For relevant posts, a single model call picks the one label whose description best fits the post, or none. The chosen label is written to the post’s tags.
Because only the description is read by the classifier, a clear, specific description matters far more than the name.
There is no sentiment field on posts. OutX classifies posts into your intent labels (tags), not into positive/negative sentiment, and relevance_score measures relevance to the watchlist, not tone. If you need sentiment, derive it from the post content yourself, or model it as an intent label (for example a label described as “frustrated with or complaining about a competitor”).

​
Timing: labels are not instant

A post is not labeled the moment you create the watchlist. Two delays stack:
  1. Collection cadence. New posts only arrive on the watchlist’s fetchFreqInHours cycle (1, 3, 6, 12, 24, 48, 72; default 12h). Until the next scan runs, there are no new posts to classify.
  2. Enrichment. Every newly collected post starts unlabeled and is classified by a background job. Historical posts pulled in when the watchlist is first created are unlabeled the same way until that job processes them.
Labeled posts therefore appear after the next fetch cycle plus the time enrichment takes to work through its queue, not instantly. An agent polling Get posts right after creating a watchlist should treat empty tags as “not classified yet,” not “no match.”

​
Editing labels is forward-only

Each post is classified into a label exactly once, when it is first enriched. Adding or changing labels with Update keyword watchlist changes how future posts are classified but does not re-label posts that were already enriched, they keep the tags they had. To re-classify already-collected posts against new labels, those posts must be explicitly re-enriched (OutX re-runs classification over roughly the last 30 days); a plain label update does not do this on its own.

​
Advanced Keyword Filtering

Each keyword can have additional filtering rules:
​
keyword
string
required
The primary keyword to search for
​
required_keywords
array
Context keywords used together with the primary keyword. How they combine is controlled by include_all_required.
​
excluded_keywords
array
None of these keywords should be present in the post (NOT logic)
​
include_all_required
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).
When you create a keyword watchlist, OutX backfills recent matching posts from its existing pool in the background, so the watchlist is not empty while it waits for the first live fetch cycle.
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
  }'

const response = await fetch("https://api.outx.ai/api-keyword-watchlist", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "YOUR_API_KEY",
  },
  body: JSON.stringify({
    name: "Remote Senior Jobs",
    keywords: [
      {
        keyword: "hiring",
        required_keywords: ["remote", "senior", "engineer"],
        excluded_keywords: ["unpaid", "intern"],
      },
    ],
    fetchFreqInHours: 6,
  }),
});

const data = await response.json();

import requests

url = 'https://api.outx.ai/api-keyword-watchlist'
headers = {
    'Content-Type': 'application/json',
    'x-api-key': 'YOUR_API_KEY'
}
payload = {
    'name': 'Remote Senior Jobs',
    'keywords': [
        {
            'keyword': 'hiring',
            'required_keywords': ['remote', 'senior', 'engineer'],
            'excluded_keywords': ['unpaid', 'intern']
        }
    ],
    'fetchFreqInHours': 6
}

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

{
  "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"
    }
  ]
}

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Remote Senior Jobs",
  "slug": "remote-senior-jobs-550e8400",
  "type": "keyword",
  "keywords": ["hiring", "job opening"],
  "fetchFreqInHours": 6,
  "created": false,
  "labels": [
    { "key": "hiring" },
    { "key": "job opening" }
  ]
}

​
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 CodeError MessageDescription
400Missing required parameter: keywordsKeywords array is required
400Invalid fetchFreqInHours valueFetch frequency must be one of: 1, 3, 6, 12, 24, 48, 72
401UnauthorizedInvalid or missing API key

​
Use Cases

Monitor hiring posts for specific roles and locations:
{
  "name": "Remote Engineering Jobs",
  "keywords": [
    {
      "keyword": "hiring",
      "required_keywords": ["engineer", "remote"],
      "excluded_keywords": ["intern", "junior"]
    }
  ]
}
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 -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
  }'

const response = await fetch("https://api.outx.ai/api-keyword-watchlist", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "YOUR_API_KEY",
  },
  body: JSON.stringify({
    prompt:
      "Track discussions about AI-native CRM tools, including competitors like Salesforce and HubSpot",
    fetchFreqInHours: 12,
  }),
});

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 discussions about AI-native CRM tools, including competitors like Salesforce and HubSpot",
    "fetchFreqInHours": 12,
}

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

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

{
  "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

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 support@outx.ai for details on plan-specific limits.
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.
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.