> ## 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. # Preview Competitor Alert > See what a Defense or Attack alert would send, before you save a change 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](https://docs.clustr-ai.com/api-reference/update-competitor-alerts.md) 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 | ```bash cURL theme={null} 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}' ``` ```python Python theme={null} 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}, ) ``` ```javascript JavaScript theme={null} 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 }), }); ``` ```json 200 theme={null} { "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" } } ``` ```json 400 theme={null} { "success": false, "error": { "message": "Pick defense or attack.", "code": "BAD_REQUEST" } } ``` ## OpenAPI ````yaml POST /notifications/competitor-alerts/preview openapi: 3.1.0 info: title: Clustr Public API description: > Programmatic access to your Clustr network: import connectors, search warm intros (opportunities), and manage target accounts. ## Authentication All endpoints require a Bearer token (API key) in the `Authorization` header. ``` Authorization: Bearer ``` API keys can be created and managed from the [API settings page](https://app.clustr-ai.com/api). version: '1.0' contact: name: Clustr Support url: https://clustr-ai.com servers: - url: https://api.clustr-ai.com/api/public description: Production security: - BearerAuth: [] paths: /notifications/competitor-alerts/preview: post: tags: - Competitor Monitoring summary: Preview Competitor Alert description: > Shows what one alert type would send, built from a real account in your workspace with recent competitor activity: 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. The body takes the same fields as [Update Competitor Alerts](/api-reference/update-competitor-alerts), plus `use_case`. They are a draft: nothing is saved, and a field you leave out reads its saved value. The preview covers the alert type even when it is turned off. `webhook_secret` is ignored. Nothing is sent. operationId: previewCompetitorAlert requestBody: required: true content: application/json: schema: allOf: - type: object required: - use_case properties: use_case: type: string enum: - defense - attack description: >- The alert type to preview: `defense` (your customers) or `attack` (accounts that are not customers). - $ref: '#/components/schemas/CompetitorAlertsUpdateRequest' examples: draft_rule: summary: Preview Attack with a stricter rule before saving it value: use_case: attack attack_min_people: 3 attack_period_days: 14 attack_comment_alone: false responses: '200': description: The example alert content: application/json: schema: $ref: '#/components/schemas/CompetitorAlertPreviewResponse' '400': description: >- `use_case` is missing or not `defense` or `attack`, or a draft setting is invalid content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: message: Pick defense or attack. code: BAD_REQUEST '401': description: Invalid or missing API key components: schemas: CompetitorAlertsUpdateRequest: type: object properties: enabled: type: boolean description: >- Whether competitor alerts go out. `false` stops every Slack post, email, webhook call and team refresh recap. attack_slack_channel_id: type: string description: >- The Slack channel Attack alerts post in, as a Slack channel id such as `C0123456789`. An empty string clears it. defense_slack_channel_id: type: string description: >- The Slack channel Defense alerts post in. May be the same as the Attack channel. An empty string clears it. attack_email_enabled: type: boolean description: >- Email each Attack alert to the account owner from your CRM and to `attack_email_recipients`. defense_email_enabled: type: boolean description: >- Email each Defense alert to the CS owner from your CRM and to `defense_email_recipients`. attack_email_recipients: type: array description: >- 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`. maxItems: 50 items: type: string format: email defense_email_recipients: type: array description: >- Extra addresses that get every Defense alert by email, at most 50. Replaces the saved list. maxItems: 50 items: type: string format: email webhook_enabled: type: boolean description: >- 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: type: string description: >- The endpoint, `https://` (or `http://`) with a host, at most 2048 characters. An empty string clears it. See [Webhook payloads](/competitor-monitoring/webhook-payload). webhook_secret: type: string writeOnly: true description: >- 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: type: integer description: >- 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. minimum: 1 maximum: 10000 attack_threshold_days: type: integer description: >- The period the threshold counts over, in days. From 1 to 365. Default 30. minimum: 1 maximum: 365 attack_threshold_scope: type: string description: >- `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. enum: - per_competitor - all_competitors alert_history_days: type: integer description: >- 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. minimum: 1 maximum: 365 customers: type: boolean description: 'Defense alerts: interactions on one of your customers.' targets: type: boolean description: >- 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: type: boolean description: >- `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: type: array items: type: string enum: - comment - like description: >- Defense alerts: the interactions that count, `comment` and/or `like`. Default both. attack_interaction_kinds: type: array items: type: string enum: - comment - like description: >- Attack alerts: the interactions that count, `comment` and/or `like`. Default both. defense_min_people: type: integer description: >- Defense alerts: an account alerts once this many people there were engaged in the period. Default 2. attack_min_people: type: integer description: >- Attack alerts: an account alerts once this many people there were engaged in the period. Default 2. defense_period_days: type: integer description: >- Defense alerts: the period the people engaged are counted over, in days (1 to 365). Default 30. attack_period_days: type: integer description: >- Attack alerts: the period the people engaged are counted over, in days (1 to 365). Default 30. defense_comment_alone: type: boolean description: >- 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: type: boolean description: >- Attack alerts: a comment is enough. An account also alerts when one comment there falls in the period, below `attack_min_people`. notify_defaults: type: boolean slack_dm: type: boolean slack_channel_id: type: string recipients: type: array items: type: string format: email CompetitorAlertPreviewResponse: type: object required: - success - data properties: success: type: boolean example: true data: type: object properties: use_case: type: string enum: - defense - attack description: The alert type previewed. rule: type: object description: >- The alert type's rule with the draft settings, and the rule in words. properties: interaction_kinds: type: array items: type: string enum: - comment - like min_people: type: integer period_days: type: integer comment_alone: type: boolean description: One comment in the period is enough, below `min_people`. text: type: string description: The rule as the alert states it. example: >- a comment, or 2+ people engaged, in the last 30 days (comments, likes) found: type: boolean description: >- False when no account had competitor activity in the period. The example fields are then empty. meets_rule: type: boolean description: >- False when the example account does not meet the rule. It is shown anyway so the message can be read. accounts: type: integer description: How many accounts would alert today under the rule. account_name: type: string description: The example account. owner: type: object description: >- The owner the alert names: the CS owner for Defense, the sales owner for Attack, from your CRM. Absent when your CRM names nobody. properties: email: type: string format: email name: type: string owner_role: type: string description: How the alert names the owner. example: CS owner people: type: array description: >- The people engaged at the example account, each with their interactions. items: type: object properties: name: type: string title: type: string linkedin_url: type: string new: type: boolean description: Engaged in an interaction no alert has reported yet. interactions: type: array items: type: object properties: type: type: string enum: - comment - like direction: type: string enum: - outbound - inbound occurred_at: type: string format: date-time competitor: type: object properties: clustr_competitor_id: type: string description: >- The competitor's Clustr ID, for example `cmp_7vj0tzfqk43c02nvjerwcx1hwq`. example: cmp_7vj0tzfqk43c02nvjerwcx1hwq id: type: string description: >- Kept for integrations built before Clustr IDs. New integrations should use `clustr_competitor_id`. name: type: string linkedin_url: type: string competitor_salesperson: type: object nullable: true properties: name: type: string title: type: string linkedin_url: type: string url: type: string description: The post the interaction is on. text: type: string new: type: boolean competitors: type: array description: The competitors engaged at the example account. items: type: string slack_text: type: string description: The Slack message, as plain text. email_subject: type: string slack_channel_id: type: string description: >- The Slack channel the alert would post in. Absent when none is set. email_to: type: array description: >- Who the alert would be emailed to, the owner first. Empty when email is off. items: type: string webhook_url: type: string description: >- The webhook the alert would be sent to. Absent when the webhook is off. when: type: string description: When alerts go out. example: After each monitoring run, one message per account ErrorResponse: type: object required: - success - error properties: success: type: boolean example: false error: type: object properties: message: type: string example: Invalid request body code: type: string example: BAD_REQUEST securitySchemes: BearerAuth: type: http scheme: bearer description: The API key you created on the API settings page of the Clustr app. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.