Preview Competitor Alert

POST

notifications

competitor-alerts

preview

curl -X POST https://api.clustr-ai.com/api/public/notifications/competitor-alerts/preview \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"use_case": "attack", "attack_min_people": 3, "attack_period_days": 14}'

import requests

requests.post(
    "https://api.clustr-ai.com/api/public/notifications/competitor-alerts/preview",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"use_case": "attack", "attack_min_people": 3, "attack_period_days": 14},
)

await fetch("https://api.clustr-ai.com/api/public/notifications/competitor-alerts/preview", {
  method: "POST",
  headers: { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ use_case: "attack", attack_min_people: 3, attack_period_days: 14 }),
});

{
  "success": true,
  "data": {
    "use_case": "attack",
    "rule": {
      "interaction_kinds": ["comment", "like"],
      "min_people": 3,
      "period_days": 14,
      "comment_alone": true,
      "text": "a comment, or 3+ people engaged, in the last 14 days (comments, likes)"
    },
    "found": true,
    "meets_rule": true,
    "accounts": 4,
    "account_name": "Acme",
    "owner": { "email": "jane@example.com", "name": "Jane Doe" },
    "owner_role": "Sales owner",
    "people": [
      {
        "name": "Sam Lee",
        "title": "Head of Security",
        "linkedin_url": "https://www.linkedin.com/in/samlee",
        "new": false,
        "interactions": [
          {
            "type": "comment",
            "direction": "outbound",
            "occurred_at": "2026-10-19T09:12:00Z",
            "competitor": {
              "clustr_competitor_id": "cmp_7vj0tzfqk43c02nvjerwcx1hwq",
              "id": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
              "name": "Wiz",
              "linkedin_url": "https://www.linkedin.com/company/wiz"
            },
            "competitor_salesperson": {
              "name": "Alex Martin",
              "title": "Account Executive",
              "linkedin_url": "https://www.linkedin.com/in/alexmartin"
            },
            "url": "https://www.linkedin.com/feed/update/urn:li:activity:7250000000000000000",
            "text": "Happy to walk you through how we handle this.",
            "new": false
          }
        ]
      }
    ],
    "competitors": ["Wiz"],
    "slack_text": "*Wiz* engaged 1 person at *Acme* (prospect)\nRule: a comment, or 3+ people engaged, in the last 14 days (comments, likes)",
    "email_subject": "Wiz engaged 1 person at Acme",
    "slack_channel_id": "C0123456789",
    "email_to": ["jane@example.com"],
    "when": "After each monitoring run, one message per account"
  }
}

{
  "success": false,
  "error": {
    "message": "Pick defense or attack.",
    "code": "BAD_REQUEST"
  }
}

Build an example of one alert type from a real account in your workspace with recent competitor activity. The response shows the message as Slack and email show it, the owner it names, where it would go, and how many accounts would alert today under the rule. Send use_case (defense or attack) and any of the fields Update Competitor Alerts takes. They are a draft: nothing is saved, and a field you leave out reads its saved value. This lets you check a new rule, channel or email list before saving it. The preview covers the alert type even when it is turned off, and webhook_secret is ignored. Nothing is sent: no Slack post, no email and no webhook call.

Response

Field	Description
`use_case`	The alert type previewed
`rule`	The rule with the draft settings, and `rule.text`, the rule in words as the alert states it
`found`	`false` when no account had competitor activity in the period. The example fields are then empty
`meets_rule`	`false` when the example account does not meet the rule. It is shown anyway, so the message can be read
`accounts`	How many accounts would alert today under the rule
`account_name`	The example account
`owner` · `owner_role`	The owner the alert names, from your CRM: the CS owner for Defense, the sales owner for Attack
`people`	The people engaged at the account, each with their interactions
`competitors`	The competitors engaged there
`slack_text` · `email_subject`	The message
`slack_channel_id` · `email_to` · `webhook_url`	Where it would go. A destination that is not set is left out, and `email_to` is empty when email is off
`when`	When alerts go out

curl -X POST https://api.clustr-ai.com/api/public/notifications/competitor-alerts/preview \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"use_case": "attack", "attack_min_people": 3, "attack_period_days": 14}'

import requests

requests.post(
    "https://api.clustr-ai.com/api/public/notifications/competitor-alerts/preview",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"use_case": "attack", "attack_min_people": 3, "attack_period_days": 14},
)

await fetch("https://api.clustr-ai.com/api/public/notifications/competitor-alerts/preview", {
  method: "POST",
  headers: { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ use_case: "attack", attack_min_people: 3, attack_period_days: 14 }),
});

{
  "success": true,
  "data": {
    "use_case": "attack",
    "rule": {
      "interaction_kinds": ["comment", "like"],
      "min_people": 3,
      "period_days": 14,
      "comment_alone": true,
      "text": "a comment, or 3+ people engaged, in the last 14 days (comments, likes)"
    },
    "found": true,
    "meets_rule": true,
    "accounts": 4,
    "account_name": "Acme",
    "owner": { "email": "jane@example.com", "name": "Jane Doe" },
    "owner_role": "Sales owner",
    "people": [
      {
        "name": "Sam Lee",
        "title": "Head of Security",
        "linkedin_url": "https://www.linkedin.com/in/samlee",
        "new": false,
        "interactions": [
          {
            "type": "comment",
            "direction": "outbound",
            "occurred_at": "2026-10-19T09:12:00Z",
            "competitor": {
              "clustr_competitor_id": "cmp_7vj0tzfqk43c02nvjerwcx1hwq",
              "id": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
              "name": "Wiz",
              "linkedin_url": "https://www.linkedin.com/company/wiz"
            },
            "competitor_salesperson": {
              "name": "Alex Martin",
              "title": "Account Executive",
              "linkedin_url": "https://www.linkedin.com/in/alexmartin"
            },
            "url": "https://www.linkedin.com/feed/update/urn:li:activity:7250000000000000000",
            "text": "Happy to walk you through how we handle this.",
            "new": false
          }
        ]
      }
    ],
    "competitors": ["Wiz"],
    "slack_text": "*Wiz* engaged 1 person at *Acme* (prospect)\nRule: a comment, or 3+ people engaged, in the last 14 days (comments, likes)",
    "email_subject": "Wiz engaged 1 person at Acme",
    "slack_channel_id": "C0123456789",
    "email_to": ["jane@example.com"],
    "when": "After each monitoring run, one message per account"
  }
}

{
  "success": false,
  "error": {
    "message": "Pick defense or attack.",
    "code": "BAD_REQUEST"
  }
}

Authorizations

Authorization

string

header

required

The API key you created on the API settings page of the Clustr app.

Body

application/json

use_case

enum<string>

required

The alert type to preview: defense (your customers) or attack (accounts that are not customers).

Available options:

defense,

attack

enabled

boolean

Whether competitor alerts go out. false stops every Slack post, email, webhook call and team refresh recap.

attack_slack_channel_id

string

The Slack channel Attack alerts post in, as a Slack channel id such as C0123456789. An empty string clears it.

defense_slack_channel_id

string

The Slack channel Defense alerts post in. May be the same as the Attack channel. An empty string clears it.

attack_email_enabled

boolean

Email each Attack alert to the account owner from your CRM and to attack_email_recipients.

defense_email_enabled

boolean

Email each Defense alert to the CS owner from your CRM and to defense_email_recipients.

attack_email_recipients

string<email>[]

Extra addresses that get every Attack alert by email, at most 50. Replaces the saved list; an empty list clears it. An address without an @ is a 400.

Maximum array length: 50

defense_email_recipients

string<email>[]

Extra addresses that get every Defense alert by email, at most 50. Replaces the saved list.

Maximum array length: 50

webhook_enabled

boolean

Sends every alert and every team refresh recap to webhook_url as a POST request. Requires webhook_url; without one the call answers 400.

webhook_url

string

The endpoint, https:// (or http://) with a host, at most 2048 characters. An empty string clears it. See Webhook payloads.

webhook_secret

string

write-only

The secret that signs each request with X-ClustR-Signature. It is write-only: the response reports has_webhook_secret in its place. Leave it out to keep the saved secret; an empty string removes it. At most 256 characters.

attack_threshold_interactions

integer

An account that is not a customer alerts when it has at least this many interactions over attack_threshold_days. From 1 to 10000. Default 10.

Required range: 1 <= x <= 10000

attack_threshold_days

integer

The period the threshold counts over, in days. From 1 to 365. Default 30.

Required range: 1 <= x <= 365

attack_threshold_scope

enum<string>

per_competitor (default) counts an account's interactions with each competitor's team on its own. all_competitors counts them across all your competitors together; the alert then names the most active one.

Available options:

per_competitor,

all_competitors

alert_history_days

integer

How old a Defense interaction or a critical comment may be and still alert, in days. From 1 to 365. Default 14. Older activity still appears in every view without alerting.

Required range: 1 <= x <= 365

customers

boolean

Defense alerts: interactions on one of your customers.

targets

boolean

Attack alerts: critical comments and threshold alerts on accounts that are not customers, both your target accounts and every other account a competitor engages with. Each alert is labelled "Target account" or "Other account" (account_scope in the webhook).

attack_other_accounts

boolean

true (default) keeps the Attack alerts on other accounts, the non-customers that are not on your target account list. false mutes them: Attack then alerts on your target accounts only.

defense_interaction_kinds

enum<string>[]

Defense alerts: the interactions that count, comment and/or like. Default both.

Available options:

comment,

like

attack_interaction_kinds

enum<string>[]

Attack alerts: the interactions that count, comment and/or like. Default both.

Available options:

comment,

like

defense_min_people

integer

Defense alerts: an account alerts once this many people there were engaged in the period. Default 2.

attack_min_people

integer

Attack alerts: an account alerts once this many people there were engaged in the period. Default 2.

defense_period_days

integer

Defense alerts: the period the people engaged are counted over, in days (1 to 365). Default 30.

attack_period_days

integer

Attack alerts: the period the people engaged are counted over, in days (1 to 365). Default 30.

defense_comment_alone

boolean

Defense alerts: a comment is enough. An account also alerts when one comment there falls in the period, below defense_min_people.

attack_comment_alone

boolean

Attack alerts: a comment is enough. An account also alerts when one comment there falls in the period, below attack_min_people.

notify_defaults

boolean

slack_dm

boolean

slack_channel_id

string

recipients

string<email>[]

Response

The example alert

success

boolean

required

Example:

true

data

object

required

Show child attributes

curl -X POST https://api.clustr-ai.com/api/public/notifications/competitor-alerts/preview \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"use_case": "attack", "attack_min_people": 3, "attack_period_days": 14}'

import requests

requests.post(
    "https://api.clustr-ai.com/api/public/notifications/competitor-alerts/preview",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"use_case": "attack", "attack_min_people": 3, "attack_period_days": 14},
)

await fetch("https://api.clustr-ai.com/api/public/notifications/competitor-alerts/preview", {
  method: "POST",
  headers: { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ use_case: "attack", attack_min_people: 3, attack_period_days: 14 }),
});

{
  "success": true,
  "data": {
    "use_case": "attack",
    "rule": {
      "interaction_kinds": ["comment", "like"],
      "min_people": 3,
      "period_days": 14,
      "comment_alone": true,
      "text": "a comment, or 3+ people engaged, in the last 14 days (comments, likes)"
    },
    "found": true,
    "meets_rule": true,
    "accounts": 4,
    "account_name": "Acme",
    "owner": { "email": "jane@example.com", "name": "Jane Doe" },
    "owner_role": "Sales owner",
    "people": [
      {
        "name": "Sam Lee",
        "title": "Head of Security",
        "linkedin_url": "https://www.linkedin.com/in/samlee",
        "new": false,
        "interactions": [
          {
            "type": "comment",
            "direction": "outbound",
            "occurred_at": "2026-10-19T09:12:00Z",
            "competitor": {
              "clustr_competitor_id": "cmp_7vj0tzfqk43c02nvjerwcx1hwq",
              "id": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
              "name": "Wiz",
              "linkedin_url": "https://www.linkedin.com/company/wiz"
            },
            "competitor_salesperson": {
              "name": "Alex Martin",
              "title": "Account Executive",
              "linkedin_url": "https://www.linkedin.com/in/alexmartin"
            },
            "url": "https://www.linkedin.com/feed/update/urn:li:activity:7250000000000000000",
            "text": "Happy to walk you through how we handle this.",
            "new": false
          }
        ]
      }
    ],
    "competitors": ["Wiz"],
    "slack_text": "*Wiz* engaged 1 person at *Acme* (prospect)\nRule: a comment, or 3+ people engaged, in the last 14 days (comments, likes)",
    "email_subject": "Wiz engaged 1 person at Acme",
    "slack_channel_id": "C0123456789",
    "email_to": ["jane@example.com"],
    "when": "After each monitoring run, one message per account"
  }
}

{
  "success": false,
  "error": {
    "message": "Pick defense or attack.",
    "code": "BAD_REQUEST"
  }
}

API Reference

Import

Search

Jobs

Network

Opportunities

Owners

Accounts

Account States

Saved Views

Workflows

Intro Requests

Notes

Record Activity

Tags

Target Accounts

Client Companies

Excluded Companies

Buyer Titles

ICP

Competitor Monitoring

Connector Refresh

Notifications

Preview Competitor Alert

Response

Authorizations

Body

Response

​Response

Authorizations

Body

Response

Response