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

# Get interactions from a watchlist

> Retrieve likes and comments for posts in a specific watchlist, with filters by interaction type, actor, and pagination.

Retrieve all interactions (likes and comments) for posts in a specific watchlist. Use this endpoint to analyze engagement activity, build custom reports, or power internal dashboards.

## Query Parameters

<ParamField query="watchlist_id" type="string" required>
  Watchlist ID to retrieve interactions from. This parameter is **required** and must be a single watchlist ID.
</ParamField>

<ParamField query="interaction_type" type="string">
  Filter by interaction type. Options:

  * `like`
  * `comment`
</ParamField>

<ParamField query="actor_ids" type="string | array">
  Optional filter for specific actors involved in the interaction. This can include:

  * OutX user IDs (for users who liked/commented)
  * Author IDs
  * Company IDs

  Accepts:

  * A single ID string
  * Multiple values as a comma-separated string
  * Multiple values as repeated query params (e.g., `actor_ids=id1&actor_ids=id2`)
</ParamField>

<ParamField query="page" type="number" default="1">
  Page number for pagination (1-indexed).
</ParamField>

<ParamField query="page_size" type="number" default="20">
  Number of interactions per page. Maximum: 100. Values above 100 fall
  back to the default.
</ParamField>

<RequestExample>
  ```bash Get interactions for a watchlist theme={null}
  curl -X GET \
    "https://api.outx.ai/api-interactions?watchlist_id=550e8400-e29b-41d4-a716-446655440000&page=1&page_size=10" \
    -H "x-api-key: YOUR_API_KEY"
  ```

  ```bash Filter by interaction type and actors theme={null}
  curl -X GET \
    "https://api.outx.ai/api-interactions?watchlist_id=550e8400-e29b-41d4-a716-446655440000&interaction_type=comment&actor_ids=user-id-1,user-id-2&page=1&page_size=20" \
    -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-interactions?` +
      new URLSearchParams({
        watchlist_id: watchlistId,
        interaction_type: "like",
        page: "1",
        page_size: "10",
      }),
    {
      headers: { "x-api-key": "YOUR_API_KEY" },
    }
  );

  const result = await response.json();
  console.log(result.pagination.total, "interactions found");
  ```

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

  headers = {"x-api-key": "YOUR_API_KEY"}
  base_url = "https://api.outx.ai/api-interactions"

  params = {
      "watchlist_id": "550e8400-e29b-41d4-a716-446655440000",
      "interaction_type": "comment",
      "page": 1,
      "page_size": 10,
  }

  response = requests.get(base_url, headers=headers, params=params)
  result = response.json()

  print("Total interactions:", result["pagination"]["total"])
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "data": [
      {
        "id": "interaction-123",
        "text": "Great insights, thanks for sharing!",
        "interaction_type": "comment",
        "created_at": 1705401600000,
        "author": {
          "id": "author-1",
          "full_name": "Jane Doe",
          "author_slug": "janedoe",
          "headline": "VP of Marketing",
          "author_type": "user"
        },
        "post": {
          "id": "post-123",
          "linkedin_post_url": "https://linkedin.com/feed/update/urn:li:activity:1234567890",
          "content": "Excited to announce our new feature...",
          "created_at": 1705400000000,
          "likes_count": 120,
          "shares_count": 10,
          "comments_count": 24,
          "bookmark": false,
          "post_type": "image",
          "linkedin_post_urn": "urn:li:activity:1234567890",
          "language": "en",
          "tags": ["product-launch", "saas"],
          "videos": null,
          "social_urn": "urn:li:activity:1234567890",
          "primary_keywords": ["AI", "automation"],
          "tracking_lists_slug": "enterprise-ai-watchlist",
          "list_info": [],
          "post_author": {
            "id": "author-1",
            "full_name": "Jane Doe",
            "author_slug": "janedoe",
            "headline": "VP of Marketing",
            "author_image_url": "https://media.licdn.com/dms/image/..."
          }
        }
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 10,
      "total": 42,
      "total_pages": 5,
      "total_likes": 30,
      "total_comments": 12
    },
    "graph_data": [
      {
        "posted_at": "2024-01-10",
        "like_count": 5,
        "comment_count": 2
      }
    ]
  }
  ```
</ResponseExample>

<ResponseField name="data" type="array">
  Array of interaction objects, each containing interaction details and the associated post.
</ResponseField>

<ResponseField name="pagination" type="object">
  Pagination metadata including current page, page size, total interactions, and totals by interaction type.
</ResponseField>

<ResponseField name="graph_data" type="array">
  Time-series data for the last 7 days, aggregating like and comment counts per day.
</ResponseField>

### Interaction Object Fields

<ResponseField name="id" type="string">
  Unique interaction identifier.
</ResponseField>

<ResponseField name="text" type="string">
  Text content of the interaction (for comments).
</ResponseField>

<ResponseField name="interaction_type" type="string">
  Type of interaction. One of: `like`, `comment`.
</ResponseField>

<ResponseField name="created_at" type="number">
  Interaction timestamp in milliseconds since epoch.
</ResponseField>

<ResponseField name="author" type="object">
  JSON object describing the interaction author (user or company).
</ResponseField>

<ResponseField name="post" type="object">
  Embedded post object with the same structure as the Posts API.
</ResponseField>

## Error Responses

| Status Code | Error Message                                                     | Description                                 |
| ----------- | ----------------------------------------------------------------- | ------------------------------------------- |
| 400         | watchlist\_id is required and must be a string                    | Missing or invalid `watchlist_id` parameter |
| 400         | Invalid watchlist ID: \<id>                                       | The provided `watchlist_id` does not exist  |
| 401         | Missing API Key / Invalid API Key                                 | API key is missing or incorrect             |
| 403         | Access denied: You don't have permission to access this watchlist | The watchlist belongs to a different team   |
| 500         | Failed to fetch interactions                                      | Internal server error                       |