Quick Start

This guide will help you make your first API requests to OutX and get familiar with the core workflows.

This quick start creates a LinkedIn keyword watchlist. Reddit is a separate watchlist type with its own endpoint (/api-reddit-watchlist, same body shape); tracking a topic on “LinkedIn and Reddit” means two create calls. See Choose a watchlist type for the platform comparison.

Prerequisites

Before you begin, make sure you have:

A live Chrome extension

At least one team member runs the OutX Chrome extension, signed into LinkedIn, active within the last 48 hours. Without it every call returns 403 Plugin installation required.

API Key

Get your API key from mentions.outx.ai/api-doc

Base URL

All requests go to: https://api.outx.ai

Your First Watchlist

Describe what you want to track in one sentence and let OutX write the keywords, the intent labels and the relevance objective. This is prompt mode, and it is the path to use unless you already know your exact match terms. Before you build several watchlists, read Design your watchlists: one watchlist carries one signal, and merging signals is the most common way an agent ends up with a feed nobody can use.

Step 1: Create a Keyword Watchlist

curl -X POST \
  "https://api.outx.ai/api-keyword-watchlist" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "prompt": "Engineering leaders picking a vector database and asking which one to use",
    "name": "Vector DB buying intent",
    "idempotency_key": "b2f0e1a4-9c33-4a71-9e0d-2f7c5a11d908"
  }'

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: 'Engineering leaders picking a vector database and asking which one to use',
      name: 'Vector DB buying intent',
      idempotency_key: crypto.randomUUID()
    })
  }
);

const { id } = await response.json();

import requests
import uuid

url = 'https://api.outx.ai/api-keyword-watchlist'
headers = {
    'Content-Type': 'application/json',
    'x-api-key': 'YOUR_API_KEY'
}
payload = {
    'prompt': 'Engineering leaders picking a vector database and asking which one to use',
    'name': 'Vector DB buying intent',
    'idempotency_key': str(uuid.uuid4()),
}

response = requests.post(url, headers=headers, json=payload)
watchlist_id = response.json()['id']

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Vector DB buying intent",
  "slug": "vector-db-buying-intent-550e8400",
  "type": "keyword",
  "created": true,
  "message": "Watchlist created. Keywords and labels are being generated in the background and will be available shortly."
}

Save the id. Send an idempotency_key on every create so a retry returns the first watchlist instead of making a second one.

Step 2: Wait for the keywords and labels

The create returns before the generation finishes. Poll the same endpoint with the id until keywords and labels are populated:

curl "https://api.outx.ai/api-keyword-watchlist?id=550e8400-e29b-41d4-a716-446655440000" \
  -H "x-api-key: YOUR_API_KEY"

A prompt that cannot produce a usable feed is refused with 422 before anything is created, and the body may carry a question to relay to your user. See When a prompt is refused.

Step 3: Retrieve Posts from Your Watchlist

Read the feed filtered to the watchlist’s default labels, which is the view the product opens on. Without labels=default you get every post collected, including the low-intent ones.

curl -X GET \
  "https://api.outx.ai/api-posts?watchlist_id=550e8400-e29b-41d4-a716-446655440000&labels=default" \
  -H "x-api-key: YOUR_API_KEY"

const watchlistId = '550e8400-e29b-41d4-a716-446655440000';
const response = await fetch(
  `https://api.outx.ai/api-posts?watchlist_id=${watchlistId}&labels=default`,
  {
    headers: {
      'x-api-key': 'YOUR_API_KEY'
    }
  }
);

const { data, count, applied_labels } = await response.json();
console.log(`Found ${count} posts filtered to ${applied_labels.join(', ')}`);

import requests

watchlist_id = '550e8400-e29b-41d4-a716-446655440000'
url = 'https://api.outx.ai/api-posts'
params = {
    'watchlist_id': watchlist_id,
    'labels': 'default',
}
headers = {'x-api-key': 'YOUR_API_KEY'}

response = requests.get(url, headers=headers, params=params)
result = response.json()
print(f"Found {result['count']} posts")

Response (abridged, see Get posts for the full post shape):

{
  "data": [
    {
      "id": "post-123",
      "content": "We are comparing pgvector and Pinecone for a 50M embedding index...",
      "author_name": "John Doe",
      "author_url": "johndoe",
      "linkedin_post_url": "https://linkedin.com/feed/update/...",
      "posted_at": "2026-08-15T10:30:00Z",
      "likes_count": 245,
      "comments_count": 32,
      "tags": ["buying-intent"],
      "relevance_score": 8
    }
  ],
  "count": 156,
  "default_labels": ["buying-intent", "competitor-mention"],
  "applied_labels": ["buying-intent", "competitor-mention"]
}

A brand-new keyword watchlist backfills recent matching posts in the background, and each post’s tags (intent labels) are written asynchronously during enrichment. Empty data or empty tags right after creation means “not processed yet”, not “no matches”. See Intent labels & defaults.

Bring your own keywords

If you already know the exact strings to match, send keywords instead of prompt. Send objective with them: it is the one sentence every collected post is scored against, and it is what makes the feed filterable.

curl -X POST \
  "https://api.outx.ai/api-keyword-watchlist" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "name": "Vector DB buying intent",
    "keywords": [
      "vector database",
      {
        "keyword": "pgvector",
        "excluded_keywords": ["tutorial", "beginner"]
      }
    ],
    "objective": "Find engineering leaders choosing a vector database so we can pitch ours"
  }'

Leave objective or labels out and OutX generates them in the background from your keywords. The response says which it had to write:

{ "created": true, "generated": { "objective": true, "labels": true } }

That is a guess at what you meant, so supply objective when you can.

Step 3: Engage with a Post

Let’s like one of the posts we retrieved:

curl -X POST \
  "https://api.outx.ai/api-like" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "post_id": "post-123",
    "user_email": "your.email@example.com",
    "actor_type": "user"
  }'

const response = await fetch(
  'https://api.outx.ai/api-like',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': 'YOUR_API_KEY'
    },
    body: JSON.stringify({
      post_id: 'post-123',
      user_email: 'your.email@example.com',
      actor_type: 'user'
    })
  }
);

const result = await response.json();
console.log(result.message);

import requests

url = 'https://api.outx.ai/api-like'
headers = {
    'Content-Type': 'application/json',
    'x-api-key': 'YOUR_API_KEY'
}
payload = {
    'post_id': 'post-123',
    'user_email': 'your.email@example.com',
    'actor_type': 'user'
}

response = requests.post(url, headers=headers, json=payload)
print(response.json()['message'])

Response:

{
  "success": true,
  "message": "Like task created successfully",
  "task_id": "task-456"
}

Advanced Filtering Examples

Filter by Date Range

Use start_date and end_date params in YYYY-MM-DD format:

curl -X GET \
  "https://api.outx.ai/api-posts?watchlist_id=YOUR_ID&start_date=2026-02-01&end_date=2026-02-28" \
  -H "x-api-key: YOUR_API_KEY"

Dates should be in YYYY-MM-DD format (e.g., 2026-02-15). End dates are inclusive - end_date=2026-02-28 includes the full day of Feb 28.

Filter by Seniority Level

Filter posts by the author’s seniority. You can pass multiple values as comma-separated:

# Single seniority
curl -X GET \
  "https://api.outx.ai/api-posts?watchlist_id=YOUR_ID&seniority_level=VP" \
  -H "x-api-key: YOUR_API_KEY"

# Multiple seniority levels
curl -X GET \
  "https://api.outx.ai/api-posts?watchlist_id=YOUR_ID&seniority_level=VP,Director,CXO" \
  -H "x-api-key: YOUR_API_KEY"

Pagination

Use page (1-indexed) and page_size (default 20). The response’s count field is the total number of matching posts, so pages run out when page * page_size >= count:

# First 20 posts (default: page=1, page_size=20)
curl -X GET \
  "https://api.outx.ai/api-posts?watchlist_id=YOUR_ID" \
  -H "x-api-key: YOUR_API_KEY"

# Posts 21-40
curl -X GET \
  "https://api.outx.ai/api-posts?watchlist_id=YOUR_ID&page=2&page_size=20" \
  -H "x-api-key: YOUR_API_KEY"

The parameter names are page and page_size on every paginated endpoint; aliases like limit, offset, per_page, or pageSize are rejected with a 400. (An offset-based alternative, range_from/range_to, also exists on /api-posts; see Get posts.)

Sort by Engagement

curl -X GET \
  "https://api.outx.ai/api-posts?watchlist_id=YOUR_ID&sort_by=popular_first" \
  -H "x-api-key: YOUR_API_KEY"

Sort options: recent (default), popular_first (by engagement), engagement (alias for popular_first).

Common Workflows

Track Industry Influencers

Create a people watchlist to monitor posts from key industry leaders:

curl -X POST \
  "https://api.outx.ai/api-people-watchlist" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "name": "Tech Leaders",
    "profiles": [
      "https://linkedin.com/in/satyanadella",
      "https://linkedin.com/in/sundarpichai",
      "elon-musk"
    ]
  }'

Monitor Competitor Companies

Track posts from competitor company pages:

curl -X POST \
  "https://api.outx.ai/api-company-watchlist" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "name": "Competitors",
    "companies": [
      "https://linkedin.com/company/openai",
      "https://linkedin.com/company/anthropic",
      "google-deepmind"
    ]
  }'

Filter Posts by Engagement

Retrieve trending posts with high engagement:

curl -X GET \
  "https://api.outx.ai/api-posts?watchlist_id=YOUR_ID&trending=true&sort_by=engagement" \
  -H "x-api-key: YOUR_API_KEY"

Automate Company Engagement

Like posts on behalf of your company page:

curl -X POST \
  "https://api.outx.ai/api-like" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "post_id": "post-123",
    "user_email": "admin@company.com",
    "actor_type": "company",
    "company_title": "Your Company Name"
  }'

Next Steps

Choose a Watchlist Type

LinkedIn vs Reddit, and which endpoint creates what

Posts API

Explore all post filtering options

Intent Labels

How posts get classified and what default labels do

Like API

Automate post likes

Need Help?

Have questions or need assistance? Contact us at support@outx.ai

AI Agent Prompt

Use the following instructions when building an AI agent that integrates with the OutX Watchlists & Engagement API.

Prerequisites

API key stored in OUTX_API_KEY environment variable
OutX Chrome extension installed and active on at least one team member’s browser

Quick Reference

Action	Method	Endpoint	Key Params
Create LinkedIn keyword watchlist	POST	`/api-keyword-watchlist`	`keywords` or `prompt` (one required), `name`, `labels`, `fetchFreqInHours`
Create Reddit watchlist	POST	`/api-reddit-watchlist`	`keywords` or `prompt` (one required), `name`, `labels`, `fetchFreqInHours`
Create people watchlist	POST	`/api-people-watchlist`	`profiles` (required), `name`, `fetchFreqInHours`
Create company watchlist	POST	`/api-company-watchlist`	`companies` (required), `name`, `fetchFreqInHours`
Retrieve posts (any watchlist type)	GET	`/api-posts`	`watchlist_id` (required), `page`, `page_size`, `labels`, `sort_by`, `start_date`, `end_date`
Like a post	POST	`/api-like`	`post_id` (required), `user_email` (required)
Comment on a post	POST	`/api-comment`	`post_id` (required), `user_email` (required), `comment_text` (required)
Check plan limits and usage	GET	`/api-team`	none

Guardrails, ALWAYS DO

Use x-api-key header for authentication
Use base URL https://api.outx.ai
Use ISO 8601 dates (YYYY-MM-DD) for start_date and end_date
Use post_id from the /api-posts response when calling /api-like or /api-comment
Retry 500 and 503 responses with exponential backoff. There is no request rate limit, so 429 is never returned for call volume
ALWAYS space LinkedIn actions out: at most 50 likes a day at least 2 minutes apart, and 25 comments a day at least 5 minutes apart, per LinkedIn account (see Recommended pace)

Guardrails, NEVER DO

Never hardcode API keys in source code
Never use fetchFreqInHours values other than 1, 3, 6, 12, 24, 48, 72
Never call /api-like or /api-comment without a valid post_id and user_email
Never assume posts appear instantly, new watchlists populate on the next fetch cycle
Never expect one call to cover two platforms: “LinkedIn and Reddit” is one POST to /api-keyword-watchlist plus one POST to /api-reddit-watchlist
Never invent pagination params: use page and page_size (limit, offset, per_page, and pageSize are rejected with a 400)
NEVER burst LinkedIn actions. /api-like and /api-comment run on a real LinkedIn account, and a burst gets that account restricted, not your API key

For the full OutX API skill file, see outx-skill.md.

Frequently Asked Questions

How long does it take for a new watchlist to start showing posts?

A LinkedIn keyword watchlist backfills recent matching posts in the background, so it is usually non-empty within minutes. Ongoing collection then follows the fetch frequency you set (fetchFreqInHours): with fetchFreqInHours at 6, each later batch arrives every 6 hours. Reddit, people and company watchlists do not backfill, so they fill from their first fetch cycle onward.

What date format should I use for start_date and end_date?

Use the YYYY-MM-DD format (ISO 8601 date format). For example, 2026-02-15. End dates are inclusive, setting end_date=2026-02-28 includes all posts from the full day of February 28.

Can I use the API without the Chrome extension?

No. The OutX Chrome extension is required for all API functionality. At least one team member must have the extension installed and active within the last 48 hours. OutX retrieves LinkedIn data through the browser extension rather than using unofficial scraping methods, so the extension is essential for the API to work.

Getting Started

Authentication (OTP)

Keyword Watchlist

People Watchlist

Company Watchlist

Reddit Watchlist

Posts & Engagement

Team & Usage

LinkedIn Data

Integrations

Prerequisites

Your First Watchlist

Step 1: Create a Keyword Watchlist

Step 2: Wait for the keywords and labels

Step 3: Retrieve Posts from Your Watchlist

Bring your own keywords

Step 3: Engage with a Post

Advanced Filtering Examples

Filter by Date Range

Filter by Seniority Level

Sort by Engagement

Common Workflows

Next Steps

Choose a Watchlist Type

Posts API

Intent Labels

Like API

Need Help?

AI Agent Prompt

Prerequisites

Quick Reference

Guardrails, ALWAYS DO

Guardrails, NEVER DO

Frequently Asked Questions

Learn More

​Prerequisites

​Your First Watchlist

​Step 1: Create a Keyword Watchlist

​Step 2: Wait for the keywords and labels

​Step 3: Retrieve Posts from Your Watchlist

​Bring your own keywords

​Step 3: Engage with a Post

​Advanced Filtering Examples

​Filter by Date Range

​Filter by Seniority Level

​Pagination

​Sort by Engagement

​Common Workflows

​Next Steps

Choose a Watchlist Type

Posts API

Intent Labels

Like API

​Need Help?

​AI Agent Prompt

​Prerequisites

​Quick Reference

​Guardrails, ALWAYS DO

​Guardrails, NEVER DO

​Frequently Asked Questions

​Learn More

Prerequisites

Your First Watchlist

Step 1: Create a Keyword Watchlist

Step 2: Wait for the keywords and labels

Step 3: Retrieve Posts from Your Watchlist

Bring your own keywords

Step 3: Engage with a Post

Advanced Filtering Examples

Filter by Date Range

Filter by Seniority Level

Pagination

Sort by Engagement

Common Workflows

Next Steps

Need Help?

AI Agent Prompt

Prerequisites

Quick Reference

Guardrails, ALWAYS DO

Guardrails, NEVER DO

Frequently Asked Questions

Learn More