Report Schema

A competitor report has two layers: a summary row (counts, status, ids) returned in list views, and the full report_data attack/defend payload returned when you fetch a single report by id.

Report object

GET /api/public/competitor-monitoring/reports returns these fields per report (the heavy report_data blob is omitted from the list). GET .../reports/{reportID} returns the same fields plus search_params and report_data.

Field	Type	Description
`id`	string	Report id
`run_id`	string	The run that produced this report
`competitor_id`	string	The monitored competitor
`competitor_name`	string	Competitor company name
`persons_tracked`	integer	Competitor team members tracked in this run
`interactions_found`	integer	Total interactions captured
`atk_count`	integer	Number of attack accounts
`def_count`	integer	Number of defend accounts
`status`	string	`COMPLETED`
`created_at`	string (RFC 3339)	When the run started
`completed_at`	string (RFC 3339)	When the report was written
`share_token`	string	Token for the shareable report view
`search_params`	object	Run parameters (detail view only)
`report_data`	object	Full attack/defend payload (detail view only)

`report_data`

The body splits into a summary header, the atk and def account lists (each an array of account signals, ranked by distinct_reps, then comments, then interactions, then the latest touch), and a reps drill-down.

summary

Field	Type	Description
`persons_tracked`	integer	Competitor team members tracked
`interactions`	integer	Total interactions folded into the report
`accounts_touched`	integer	Distinct accounts the competitor engaged
`open_deals_at_risk`	integer	Accounts you own that have an open deal and competitor activity
`atk_accounts`	integer	Count of attack accounts
`def_accounts`	integer	Count of defend accounts

atk / def (account signal)

Each entry in atk and def is one account the competitor touched. def accounts are those you own (matched to a CRM company or owner); atk accounts are everything else.

Field	Type	Description
`account_key`	string	Stable account identity (`domain:…`, else `company:…`, else `person:…`)
`company_name`	string	Resolved company name
`domain`	string	Resolved company domain
`owner_email`	string	CRM owner email (defend accounts)
`owner_name`	string	CRM owner name
`signal_score`	number	Deprecated. Older reports carry a composite score here; new reports leave it out
`distinct_reps`	integer	Distinct competitor reps that touched this account
`interactions`	integer	Interactions on this account
`comments`	integer	How many were comments
`reactions`	integer	How many were reactions/likes
`we_own`	boolean	True for defend accounts (CRM company or owner matched)
`has_open_deal`	boolean	An open CRM deal exists on the account
`at_risk`	boolean	`we_own` AND `has_open_deal`
`targets`	array	People the competitor engaged at this account

Each targets entry:

Field	Type	Description
`target_linkedin_id`	string	The engaged person
`target_name`	string	Their name
`we_know_target`	boolean	Matches a CRM contact you already touched

reps

Per competitor rep, the interactions they made.

Field	Type	Description
`rep_linkedin_id`	string	The competitor rep
`rep_name`	string	Their name
`rep_title`	string	Their headline/title
`role_bucket`	string	Coarse GTM role classification
`interactions`	array	Their individual interactions

Each interactions entry:

Field	Type	Description
`target_linkedin_id`	string	Who they engaged
`target_name`	string	Their name
`company_name`	string	Resolved company
`domain`	string	Resolved domain
`interaction_type`	string	`comment`, `like`, `reaction`, … (comments are weighted more heavily)
`when`	string (RFC 3339)	When it happened
`post_url`	string	Link to the post
`post_preview`	string	Snippet of the post
`owner_email`	string	CRM owner of the target’s account
`owner_name`	string	CRM owner name
`has_open_deal`	boolean	Open deal on the account
`we_own`	boolean	You own the account
`we_know_target`	boolean	You already know this person

How accounts are ranked

Within atk and def, the account the most competitor reps touched comes first, because several of their people on one account is the strongest sign. Ties go to the account with more comments, then more interactions, then the most recent touch.

Example report

GET /api/public/competitor-monitoring/reports/{reportID}:

{
  "success": true,
  "data": {
    "id": "a7b8c9d0-1234-5678-9abc-def012345678",
    "run_id": "5f6e7d8c-9012-3456-789a-bcdef0123456",
    "competitor_id": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "competitor_name": "Globex Inc",
    "persons_tracked": 12,
    "interactions_found": 47,
    "atk_count": 8,
    "def_count": 3,
    "status": "COMPLETED",
    "created_at": "2026-06-29T09:00:00Z",
    "completed_at": "2026-06-29T09:06:12Z",
    "share_token": "9b2f1e7a-0c44-4d2a-9f3b-7e1c2d4a5b6c",
    "search_params": {},
    "report_data": {
      "summary": {
        "persons_tracked": 12,
        "interactions": 47,
        "accounts_touched": 11,
        "open_deals_at_risk": 2,
        "atk_accounts": 8,
        "def_accounts": 3
      },
      "atk": [
        {
          "account_key": "domain:acme.com",
          "company_name": "Acme Corp",
          "domain": "acme.com",
          "distinct_reps": 3,
          "interactions": 6,
          "comments": 2,
          "reactions": 4,
          "we_own": false,
          "has_open_deal": false,
          "at_risk": false,
          "targets": [
            { "target_linkedin_id": "jane-smith", "target_name": "Jane Smith", "we_know_target": true },
            { "target_linkedin_id": "raj-patel", "target_name": "Raj Patel", "we_know_target": false }
          ]
        }
      ],
      "def": [
        {
          "account_key": "domain:initech.com",
          "company_name": "Initech",
          "domain": "initech.com",
          "owner_email": "alice@yourco.com",
          "owner_name": "Alice Martin",
          "distinct_reps": 1,
          "interactions": 2,
          "comments": 1,
          "reactions": 1,
          "we_own": true,
          "has_open_deal": true,
          "at_risk": true,
          "targets": [
            { "target_linkedin_id": "peter-g", "target_name": "Peter Gibbons", "we_know_target": true }
          ]
        }
      ],
      "reps": [
        {
          "rep_linkedin_id": "bob-seller",
          "rep_name": "Bob Seller",
          "rep_title": "Account Executive at Globex",
          "role_bucket": "sales",
          "interactions": [
            {
              "target_linkedin_id": "jane-smith",
              "target_name": "Jane Smith",
              "company_name": "Acme Corp",
              "domain": "acme.com",
              "interaction_type": "comment",
              "when": "2026-06-24T14:12:00Z",
              "post_url": "https://www.linkedin.com/feed/update/urn:li:activity:123",
              "post_preview": "Excited to share our new pricing...",
              "has_open_deal": false,
              "we_own": false,
              "we_know_target": true
            }
          ]
        }
      ]
    }
  }
}

Report-ready webhook

If the competitor report’s webhook is on (see Update Delivery Config), Clustr POSTs a competitor_monitoring.report_ready event to your URL each time the report goes out. There is one report for the whole workspace, covering every competitor, so the payload lists the competitors and every account the report covers, uncapped. A workspace that splits its audiences into routes gets one POST per route, each carrying that route’s accounts. The report covers everything since the previous one (the last 14 days for the first), at most once per monitoring period, and only when a competitor’s people engaged someone at a company in that time. An account is a company: people whose company is not known are counted in people_no_company.

{
  "event": "competitor_monitoring.report_ready",
  "tenant_id": "4e1b2c3d-5f6a-4b7c-8d9e-0a1b2c3d4e5f",
  "competitor_id": "",
  "competitor_name": "",
  "competitors": [
    { "id": "c1a2b3c4-d5e6-7890-abcd-ef1234567890", "name": "Globex Inc" },
    { "id": "d2b3c4d5-e6f7-8901-bcde-f12345678901", "name": "Wiz" }
  ],
  "persons_tracked": 12,
  "interactions_found": 47,
  "atk_count": 8,
  "def_count": 3,
  "at_risk": 1,
  "link": "https://app.clustr-ai.com/competitor-monitoring?from=2026-09-30&to=2026-10-07",
  "period_from": "2026-09-30T09:12:00Z",
  "period_to": "2026-10-14T09:15:00Z",
  "accounts_engaged": 1,
  "accounts_quiet": 2,
  "people_no_company": 3,
  "crm_connected": true,
  "accounts": [
    {
      "competitor_ids": ["c1a2b3c4-d5e6-7890-abcd-ef1234567890"],
      "competitor_names": "Globex Inc",
      "company_name": "Initech",
      "company_domain": "initech.com",
      "people": 2,
      "interactions": 5,
      "comments": 1,
      "has_open_deal": true,
      "in_crm": true,
      "has_critical": false,
      "icp_match": true,
      "reason": "open deal",
      "is_customer": false,
      "is_target": true,
      "intent_label": "evaluating",
      "link": "https://app.clustr-ai.com/competitor-monitoring?account=initech.com&c=c1a2b3c4-d5e6-7890-abcd-ef1234567890&from=2026-09-30&to=2026-10-07"
    }
  ]
}

Field	Type	Description
`event`	string	Always `competitor_monitoring.report_ready`
`tenant_id`	string	Your workspace id
`competitor_id`	string	Always `""`. Kept so an older parser does not fail; read `competitors`
`competitor_name`	string	Always `""`. Kept for the same reason
`competitors`	object[]	Every competitor the report covers, `{id, name}`, sorted by id
`persons_tracked`	integer	Competitor team members tracked, summed over competitors
`interactions_found`	integer	Interactions captured, summed over competitors
`atk_count`	integer	Attack accounts, summed over competitors
`def_count`	integer	Defense accounts, summed over competitors
`at_risk`	integer	Customer accounts that also have an open deal, summed over competitors
`link`	string	The competitor workspace over the report’s period
`period_from`	string (RFC 3339)	The start of the period the report covers: the previous report, or 14 days back for the first
`period_to`	string (RFC 3339)	The end of the period: when the report was built
`accounts_engaged`	integer	How many accounts `accounts` lists
`accounts_quiet`	integer	Accounts left out because nothing changed since they were last reported
`people_no_company`	integer	People engaged whose company is not known. They are not accounts
`crm_connected`	boolean	A CRM is connected. When `false`, `has_open_deal` and `in_crm` were not checked
`accounts`	object[]	Every account the report covers (see below)

Each element of accounts:

Field	Type	Description
`competitor_ids`	string[]	The competitors working this account
`competitor_names`	string	Their names, comma separated
`company_name`	string	The account
`company_domain`	string	Its domain, or `""` when unknown
`people`	integer	Distinct people engaged at the account
`interactions`	integer	Their people’s interactions with people at the account (likes and comments on those people’s posts)
`comments`	integer	How many of them are comments. Pleasantries such as “Congrats!” count as likes
`has_open_deal`	boolean	The account has an open deal in your CRM
`in_crm`	boolean	The account is in your CRM
`has_critical`	boolean	At least one comment was classified critical
`icp_match`	boolean	The account fits your ICP
`reason`	string	`open deal`, `in CRM`, `in ICP` or `""`: why it matters, first match wins
`is_customer`	boolean	The account is on your client list
`is_target`	boolean	The account is on your target account list
`intent_label`	string	The newest buying intent a post there showed: `hiring_for`, `evaluating`, `migrating`, `rfp` or `budget_or_project`. `""` when none
`link`	string	The account in the competitor workspace

The request carries X-ClustR-Event: competitor_monitoring.report_ready and is not signed: the report’s delivery settings have no secret. It goes through the same queue as the alert webhooks, with the same retries; see Webhook payloads. The matching email carries the same counts and a button to link.

Getting Started

Views & Workflows

Competitor Monitoring

Integrations

CRM Cleaning

Report object

`report_data`

summary

atk / def (account signal)

reps

How accounts are ranked

Example report

Report-ready webhook

​Report object

​report_data

​summary

​atk / def (account signal)

​reps

​How accounts are ranked

​Example report

​Report-ready webhook

Report object

`report_data`

summary

atk / def (account signal)

reps

How accounts are ranked

Example report

Report-ready webhook