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

# List Competitor Interactions

> The Signals feed — every competitor-rep interaction with a person at one of your accounts

The Signals feed. One row per interaction (comment, reaction, share) between a tracked competitor's rep and a person at one of your accounts, across every competitor you monitor.

Each row carries who did it, who they engaged, that person's company, the ICP verdict, your live CRM state for the account (in CRM, open deal, owner) and the LLM `is_critical` verdict with the reason it gave. This is the row data behind the Signals table in the app, with the same filters.

Rows are ranked open-deal → in-CRM → critical → recency. Pass `order=recent` for a pure newest-first log, or `order=seniority` to rank a founder's like above an SDR's.

Offset-paginated: pass the previous response's `next_offset` as `offset` until `has_more` is `false`.

## Query parameters

<ParamField query="competitor_id" type="string">
  Scope to one tracked competitor. Repeatable for a multi-select (`?competitor_id=a&competitor_id=b`). Omit for all.
</ParamField>

<ParamField query="from" type="string">
  Window start, RFC 3339 (e.g. `2026-07-01T00:00:00Z`).
</ParamField>

<ParamField query="to" type="string">
  Window end, RFC 3339.
</ParamField>

<ParamField query="crm" type="string" default="all">
  CRM scope for the engaged person's company: `all`, `in_crm`, `not_in_crm`, `open_deal`, or
  `customer`.

  `customer` keeps only accounts you already own. It resolves against your workspace's
  customer definition (the CRM field and values you set in monitoring settings, e.g. HubSpot
  `lifecyclestage` = `customer`), so a workspace that has defined no values matches nothing.
  This is the scope to use for a retention view: a competitor working an account you have
  already closed is a different alert from one working a prospect.
</ParamField>

<ParamField query="critical" type="string" default="all">
  `critical_only` keeps just the LLM-flagged interactions.
</ParamField>

<ParamField query="type" type="string">
  Engagement kind: `comment`, `like` or `share`. Repeatable.
</ParamField>

<ParamField query="role" type="string">
  Competitor-rep role: `bdr`, `ae`, `csm`, `founder` or `other`. Repeatable.
</ParamField>

<ParamField query="seniority" type="string">
  Competitor-rep seniority: `high`, `mid`, `low` or `unknown`. Repeatable.
</ParamField>

<ParamField query="target" type="string">
  Scope to ONE engaged person, by their LinkedIn id. This is the drilldown behind [the prospect-grouped view](/api-reference/list-competitor-interaction-prospects).
</ParamField>

<ParamField query="order" type="string">
  `recent` for arrival order, `seniority` to rank by the engaging rep's seniority. Omit to keep the threat ranking.
</ParamField>

<ParamField query="limit" type="integer" default="50">
  Page size, max 200.
</ParamField>

<ParamField query="offset" type="integer" default="0">
  Offset for the next page.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -G https://api.clustr-ai.com/api/public/competitor-interactions \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -d crm=open_deal \
    -d critical=critical_only \
    -d order=recent \
    -d limit=50
  ```

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

  requests.get(
      "https://api.clustr-ai.com/api/public/competitor-interactions",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
      params=[
          ("competitor_id", "c1a2b3c4-d5e6-7890-abcd-ef1234567890"),
          ("type", "comment"),
          ("type", "like"),
          ("crm", "open_deal"),
          ("limit", 50),
      ],
  )
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams();
  params.append("competitor_id", "c1a2b3c4-d5e6-7890-abcd-ef1234567890");
  params.append("type", "comment");
  params.append("type", "like");
  params.set("crm", "open_deal");

  await fetch(`https://api.clustr-ai.com/api/public/competitor-interactions?${params}`, {
    headers: { Authorization: "Bearer YOUR_API_KEY" },
  });
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "data": {
      "interactions": [
        {
          "competitor_id": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
          "competitor_name": "Globex Inc",
          "rep_linkedin_id": "samir-k",
          "rep_name": "Samir Khoury",
          "rep_title": "Enterprise AE",
          "target_linkedin_id": "dana-p",
          "target_name": "Dana Patel",
          "target_job_title": "VP Revenue Operations",
          "target_company_name": "Northwind Trading",
          "target_company_domain": "northwind.com",
          "target_company_numeric_id": "1553894",
          "interaction_type": "comment",
          "engagement_at": "2026-07-28T14:02:11Z",
          "post_url": "https://www.linkedin.com/feed/update/urn:li:activity:7212345678901234567",
          "post_key": "urn:li:activity:7212345678901234567",
          "content_preview": "Happy to walk you through how we handle this at Globex — DM me.",
          "icp_match": true,
          "icp_matched_keyword": "revenue operations",
          "is_critical": true,
          "critical_reason": "Rep offered a direct product comparison to a VP at an account with an open deal.",
          "crm_company_id": "70123456789",
          "owner_name": "Alex Rivera",
          "owner_email": "alex@yourcompany.com",
          "has_open_deal": true,
          "deal_name": "Northwind - Platform expansion",
          "deal_stage": "Negotiation",
          "is_customer": false,
          "lifecycle_stage": "opportunity"
        }
      ],
      "has_more": true,
      "next_offset": 50
    }
  }
  ```

  ```json 403 theme={null}
  {
    "success": false,
    "error": {
      "message": "Competitor monitoring is not enabled for this tenant",
      "code": "FORBIDDEN"
    }
  }
  ```
</ResponseExample>