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

# Competitor Monitoring

> Track a competitor's go-to-market team and see which of your accounts they are working

Competitor Monitoring watches a competitor's go-to-market team on LinkedIn and tells you which accounts they are engaging, scored and split into **attack** and **defend** signals.

* **Attack (ATK)**: the competitor is reaching accounts you care about but do not own yet. White space to go win.
* **Defend (DEF)**: the competitor is touching accounts you already own. Deals to protect.

Each run scrapes the tracked competitor's team activity (comments and reactions), resolves the people they engaged to companies, layers in your CRM context (owner, open deals, "do we already know this person"), and ranks every touched account by a signal score.

<Info>
  Competitor Monitoring is an add-on. Your workspace needs the feature enabled and a slot allowance granted by Clustr. Contact support to turn it on. Calls return `403` when the feature is off.
</Info>

## How it works

```
Register competitor → first scan starts → weekly scans thereafter
                          ↓
        Signals (live feed) · Accounts · Reports (ATK/DEF)
                          ↓
              Delivery (email · Slack · webhook)
```

1. **Register** the competitors you want to track. Each active competitor consumes one slot, and **adding one starts its first scan immediately**.
2. **Turn the weekly schedule on** to keep scanning. It starts switched off, so adding a competitor scans it once and nothing repeats until you enable the schedule. There is no on-demand trigger — see [When scans run](#when-scans-run).
3. **Read** the results three ways: the live [Signals feed](/api-reference/list-competitor-interactions) (one row per interaction), the [accounts overview](/api-reference/list-competitor-accounts) (one row per account, ranked, with your CRM context), and the periodic [attack/defend report](/api-reference/list-competitor-reports).
4. **Receive** a report-ready notification through any channels you have configured (email, Slack, webhook).

## The slot model

The number of competitors you can actively monitor is a per-workspace entitlement (`competitor_monitor_slot_limit`) granted by Clustr. `GET /competitors` returns your current usage:

```json theme={null}
"slot_usage": { "used": 2, "active": 2, "limit": 5 }
```

* `active` counts competitors with `status: active`. Only active competitors are run and only they consume a slot.
* Registering a competitor when `active` already equals `limit` returns `409`.
* **Pausing** a competitor (`status: paused`) frees its slot without deleting it. Resuming it (back to `active`) is subject to the slot limit again and returns `409` when full.

## Authentication

All `/api/public/*` requests authenticate with your workspace API key as a Bearer token. The key resolves to your workspace, so you never pass a tenant id yourself.

```
Authorization: Bearer <your_api_key>
```

See [Authentication](/authentication) for creating and managing keys. The same key drives the [MCP server](/mcp-server).

## Quickstart

<Steps>
  <Step title="Register a competitor">
    ```bash theme={null}
    curl -X POST https://api.clustr-ai.com/api/public/competitors \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "company_name": "Globex Inc",
        "domain": "globex.com",
        "linkedin_url": "https://www.linkedin.com/company/globex"
      }'
    ```

    The response echoes the created competitor and your updated `slot_usage`. Note the `id`.
  </Step>

  <Step title="Wait for the first scan">
    Registering started it. Watch it with:

    ```bash theme={null}
    curl https://api.clustr-ai.com/api/public/competitor-runs \
      -H "Authorization: Bearer YOUR_API_KEY"
    ```

    ```json theme={null}
    { "success": true, "data": { "runs": [ { "competitor_id": "...", "status": "running", "started_at": "2026-07-29T09:00:04Z" } ] } }
    ```

    A scan takes several minutes per competitor.
  </Step>

  <Step title="Read the Signals feed">
    One row per interaction between a competitor's rep and a person at one of your accounts, with the ICP verdict, your CRM state and the LLM critical verdict:

    ```bash 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
    ```

    Or ask the account-level question instead — which of your accounts are being worked, ranked:

    ```bash theme={null}
    curl https://api.clustr-ai.com/api/public/competitor-accounts \
      -H "Authorization: Bearer YOUR_API_KEY"
    ```
  </Step>

  <Step title="Read the report">
    List reports (newest first), then fetch one by id for the full attack/defend payload:

    ```bash theme={null}
    curl https://api.clustr-ai.com/api/public/competitor-monitoring/reports \
      -H "Authorization: Bearer YOUR_API_KEY"

    curl https://api.clustr-ai.com/api/public/competitor-monitoring/reports/REPORT_ID \
      -H "Authorization: Bearer YOUR_API_KEY"
    ```

    See the [report schema](/competitor-monitoring/report-schema) for every field.
  </Step>
</Steps>

## When scans run

A competitor scan fires on exactly two events:

1. **You add a competitor.** [Registering one](/api-reference/register-competitor) starts its first scan straight away, so a new competitor has data within minutes rather than at the end of the week.
2. **The weekly schedule fires**, once you have enabled it. Scheduled scanning is opt-in and starts disabled, so no recurring scan runs for a workspace until an admin switches it on. Enabling it defaults to Monday 08:00 UTC. Read it with [GET /competitor-monitoring/schedule](/api-reference/get-monitoring-schedule) and move the day, hour or timezone with [the PUT](/api-reference/update-monitoring-schedule).

<Note>
  **There is no on-demand trigger, in the app, in the API or over MCP.** `POST /competitor-monitoring/run` and the `start_competitor_monitoring` MCP tool were both removed.

  A scan bills per tracked rep per run, and what it watches for — a competitor working one of your accounts — plays out over weeks, not hours. Re-running on demand cost money without changing what the data said, which is also why `cadence` is pinned to weekly rather than being a dropdown. Use [GET /competitor-runs](/api-reference/list-competitor-runs) to see what is in flight.
</Note>

## Run it from your AI assistant

The [MCP server](/mcp-server) exposes Competitor Monitoring as tools, so you can drive the whole loop in natural language from Claude, Cursor, or ChatGPT:

Everything on this page is available as an MCP tool — anything you can do in the app you can do from your assistant, and from the API.

| Tool                                                                                                                                                    | Description                                                                            |
| ------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `list_competitors` · `register_competitor` · `update_competitor` · `pause_competitor` · `delete_competitor`                                             | Manage the tracked set. Registering starts the first scan.                             |
| `list_competitor_interactions` · `list_competitor_interaction_prospects` · `export_competitor_interactions`                                             | The Signals feed, per interaction or per engaged person, plus the whole-history export |
| `list_competitor_accounts` · `list_competitor_account_interactions`                                                                                     | Which of your accounts are being worked, ranked, and one account's full history        |
| `list_competitor_summaries` · `get_competitor_detail` · `list_competitor_runs`                                                                          | Per-competitor tallies, the full battlecard, and scan status                           |
| `snooze_competitor_interaction` · `dismiss_competitor_target` · `undismiss_competitor_target` · `list_dismissed_competitor_targets`                     | Triage: hide one interaction until it expires, or silence a person for good            |
| `log_competitor_interaction_to_crm`                                                                                                                     | Write a critical signal onto the matched CRM company as a note                         |
| `get_competitor_monitoring_schedule` · `update_competitor_monitoring_schedule` · `get_competitor_delivery_config` · `update_competitor_delivery_config` | When scans run, and where the reports go                                               |
| `list_competitor_reports` · `get_competitor_report`                                                                                                     | The periodic attack/defend reports                                                     |

Example prompts:

* *"Add Globex as a competitor to monitor"*
* *"Which of my open-deal accounts did competitors touch this week?"*
* *"Show me every critical signal from Globex's founders and AEs in the last 30 days"*
* *"Who at Northwind Trading have our competitors been talking to?"*
* *"Show me the latest competitor report and which accounts are at risk"*

## Delivery

When a run completes, Clustr fans the report out to the channels enabled in your workspace's competitor delivery config:

* **Email**: a summary email with the attack/defend counts and a link to the full report. Sent to your configured recipients.
* **Slack**: a one-line summary posted to your configured channel.
* **Webhook**: a `competitor_monitoring.report_ready` event POSTed to your endpoint. See [webhook payload](/competitor-monitoring/report-schema#report-ready-webhook).

Delivery is best-effort per channel: a failure on one channel never blocks the others.