> ## Documentation Index
> Fetch the complete documentation index at: https://www.outx.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start

> Get started with the OutX LinkedIn API in minutes. Create your first keyword watchlist, retrieve posts, and automate engagement with code examples.

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

<Note>
  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](/docs/api-reference/watchlist/overview) for the platform comparison.
</Note>

## Prerequisites

Before you begin, make sure you have:

<Steps>
  <Step title="API Key">
    Get your API key from [mentions.outx.ai/api-doc](https://mentions.outx.ai/api-doc)
  </Step>

  <Step title="Base URL">
    All requests go to: `https://api.outx.ai`
  </Step>
</Steps>

## Your First Watchlist

Let's create a keyword watchlist to track LinkedIn posts about AI and machine learning.

### Step 1: Create a Keyword Watchlist

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST \
    "https://api.outx.ai/api-keyword-watchlist" \
    -H "Content-Type: application/json" \
    -H "x-api-key: YOUR_API_KEY" \
    -d '{
      "name": "AI & ML Trends",
      "keywords": [
        "artificial intelligence",
        {
          "keyword": "machine learning",
          "required_keywords": ["python", "tensorflow"],
          "excluded_keywords": ["beginner", "tutorial"]
        }
      ],
      "fetchFreqInHours": 12
    }'
  ```

  ```javascript JavaScript theme={null}
  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: 'AI & ML Trends',
        keywords: [
          'artificial intelligence',
          {
            keyword: 'machine learning',
            required_keywords: ['python', 'tensorflow'],
            excluded_keywords: ['beginner', 'tutorial']
          }
        ],
        fetchFreqInHours: 12
      })
    }
  );

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests
  import json

  url = 'https://api.outx.ai/api-keyword-watchlist'
  headers = {
      'Content-Type': 'application/json',
      'x-api-key': 'YOUR_API_KEY'
  }
  payload = {
      'name': 'AI & ML Trends',
      'keywords': [
          'artificial intelligence',
          {
              'keyword': 'machine learning',
              'required_keywords': ['python', 'tensorflow'],
              'excluded_keywords': ['beginner', 'tutorial']
          }
      ],
      'fetchFreqInHours': 12
  }

  response = requests.post(url, headers=headers, json=payload)
  print(response.json())
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "AI & ML Trends",
  "slug": "ai-ml-trends-550e8400",
  "type": "keyword",
  "keywords": ["artificial intelligence", "machine learning"],
  "fetchFreqInHours": 12,
  "created": true
}
```

<Tip>
  Save the `id` from the response - you'll need it to retrieve posts from this watchlist!
</Tip>

### Step 2: Retrieve Posts from Your Watchlist

Now let's fetch posts from the watchlist we just created:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET \
    "https://api.outx.ai/api-posts?watchlist_id=550e8400-e29b-41d4-a716-446655440000&page=1" \
    -H "x-api-key: YOUR_API_KEY"
  ```

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

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

  ```python Python theme={null}
  import requests

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

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

**Response (abridged, see [Get posts](/docs/api-reference/engagement/posts/get) for the full post shape):**

```json theme={null}
{
  "data": [
    {
      "id": "post-123",
      "content": "Exciting developments in machine learning with Python and TensorFlow...",
      "author_name": "John Doe",
      "author_url": "johndoe",
      "linkedin_post_url": "https://linkedin.com/feed/update/...",
      "posted_at": "2024-01-15T10:30:00Z",
      "likes_count": 245,
      "comments_count": 32,
      "tags": ["ml-engineering"],
      "relevance_score": 8
    }
  ],
  "count": 156
}
```

<Info>
  A brand-new 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](/docs/api-reference/concepts/intent-labels).
</Info>

### Step 3: Engage with a Post

Let's like one of the posts we retrieved:

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```javascript JavaScript theme={null}
  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);
  ```

  ```python Python theme={null}
  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'])
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "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:

```bash theme={null}
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"
```

<Tip>
  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.
</Tip>

### Filter by Seniority Level

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

```bash theme={null}
# 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`:

```bash theme={null}
# 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](/docs/api-reference/engagement/posts/get#pagination).)

### Sort by Engagement

```bash theme={null}
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

<AccordionGroup>
  <Accordion title="Track Industry Influencers" icon="users">
    Create a people watchlist to monitor posts from key industry leaders:

    ```bash theme={null}
    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"
        ]
      }'
    ```
  </Accordion>

  <Accordion title="Monitor Competitor Companies" icon="building">
    Track posts from competitor company pages:

    ```bash theme={null}
    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"
        ]
      }'
    ```
  </Accordion>

  <Accordion title="Filter Posts by Engagement" icon="fire">
    Retrieve trending posts with high engagement:

    ```bash theme={null}
    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"
    ```
  </Accordion>

  <Accordion title="Automate Company Engagement" icon="building-circle-check">
    Like posts on behalf of your company page:

    ```bash theme={null}
    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"
      }'
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Choose a Watchlist Type" icon="list-check" href="/docs/api-reference/watchlist/overview">
    LinkedIn vs Reddit, and which endpoint creates what
  </Card>

  <Card title="Posts API" icon="newspaper" href="/docs/api-reference/engagement/posts/get">
    Explore all post filtering options
  </Card>

  <Card title="Intent Labels" icon="tags" href="/docs/api-reference/concepts/intent-labels">
    How posts get classified and what default labels do
  </Card>

  <Card title="Like API" icon="heart" href="/docs/api-reference/engagement/like/create">
    Automate post likes
  </Card>
</CardGroup>

## Need Help?

<Info>
  Have questions or need assistance? Contact us at [support@outx.ai](mailto:support@outx.ai)
</Info>

## 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`                                                                 |
| Create company watchlist            | POST   | `/api-company-watchlist` | `companies` (required), `name`                                                                |
| 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

1. Use `x-api-key` header for authentication
2. Use base URL `https://api.outx.ai`
3. Use ISO 8601 dates (`YYYY-MM-DD`) for `start_date` and `end_date`
4. Use `post_id` from the `/api-posts` response when calling `/api-like` or `/api-comment`
5. Handle 429 rate limit errors with exponential backoff

### Guardrails, NEVER DO

1. Never hardcode API keys in source code
2. Never use `fetchFreqInHours` values other than 1, 3, 6, 12, 24, 48, 72
3. Never call `/api-like` or `/api-comment` without a valid `post_id` and `user_email`
4. Never assume posts appear instantly, new watchlists populate on the next fetch cycle
5. 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`
6. Never invent pagination params: use `page` and `page_size` (`limit`, `offset`, `per_page`, and `pageSize` are rejected with a 400)

<Info>
  For the full OutX API skill file, see [outx-skill.md](https://outx.ai/docs/outx-skill.md).
</Info>

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="How long does it take for a new watchlist to start showing posts?">
    It depends on the fetch frequency you set (`fetchFreqInHours`). After creating a watchlist, OutX begins scanning LinkedIn on the next fetch cycle. For example, if you set `fetchFreqInHours` to 6, you can expect the first results within 6 hours. You can set it as low as 1 hour for faster initial results.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

***

## Learn More

* [LinkedIn Social Listening Guide](https://www.outx.ai/blog/guide-social-listening-linkedin)
* [LinkedIn API Guide](https://www.outx.ai/blog/linkedin-api-guide)
* [LinkedIn Monitoring Guide](https://www.outx.ai/blog/linkedin-monitoring-guide-2025)