get_cross_event_patterns

This page documents the Python MCP surface (mcp.heybtw.com). It reflects mcp-server/tools/cross_event_patterns.py as of this page’s publication — see Schema stability.

Purpose

get_cross_event_patterns groups event attendance by account (domain) and returns each account’s full event history with a computed engagement trajectory — increasing, stable, decreasing, or new. It’s the tool for “who’s compounding engagement across our program,” not just “who came to one event.”

When to use this

“Which accounts have attended 3+ events and are still open pipeline?”
Identifying accelerating accounts for a targeted follow-up or invite campaign — feed the output into get_account_relationship for the ones worth a deeper look.
Any account-trajectory question. This is the only tool that classifies trajectories. get_workspace_overview used to carry an engagement_health rollup; HEY-1913 removed it precisely because it diverged from this tool, so route those questions here.

Parameters

Name	Type	Required	Default	Description	Example
`domain`	string	No	`null`	Filter to accounts whose domain contains this substring.	`"lighthouse"`
`min_events`	integer	No	`2`	Only include accounts with at least this many distinct events attended.	`3`
`limit`	integer	No	`20`	Max accounts returned. Clamped to `[1, 500]`.	`50`
`include_own_domain`	boolean	No	`false`	Include the calling workspace’s own domain (normally excluded as “not a customer/prospect”).	`true`
`include_partner_accounts`	boolean	No	`false`	Include accounts identified as one of your own partner organizations (their staff attending co-hosted events otherwise inflates engagement signals).	`true`

Default behavior

Called with no parameters, returns up to 20 accounts with 2 or more distinct events attended, sorted by event count descending then most-recent activity, excluding the workspace’s own domain and any known partner domains. This is the single most consequential default to know: an account with exactly 1 event attended will never appear unless you pass min_events: 1.

Sample request

{
  "tool": "get_cross_event_patterns",
  "arguments": { "min_events": 2, "limit": 20 }
}

Sample response

{
  "tool": "get_cross_event_patterns",
  "query_time_ms": 55.1,
  "result_count": 1,
  "data": [
    {
      "company": "Lighthouse Robotics",
      "domain": "lighthouserobotics.example",
      "account_role": "external",
      "events": [
        {
          "event_name": "Automation Roundtable Q1",
          "channel_id": "chn_71c02",
          "event_date": "2026-02-04T00:00:00+00:00",
          "attendee_count": 1,
          "checked_in_count": 1,
          "mql": true,
          "opportunity": false
        },
        {
          "event_name": "Robotics Summit SF 2026",
          "channel_id": "chn_88af1",
          "event_date": "2026-06-18T00:00:00+00:00",
          "attendee_count": 3,
          "checked_in_count": 3,
          "mql": true,
          "opportunity": true
        }
      ],
      "total_events": 2,
      "first_seen": "2026-02-04T00:00:00+00:00",
      "last_seen": "2026-06-18T00:00:00+00:00",
      "trajectory": "increasing"
    }
  ],
  "metadata": {
    "data_sources_queried": ["Channel", "EventSignUp"],
    "date_range_applied": null,
    "filters_applied": { "domain": null, "min_events": 2, "limit": 20, "include_partner_accounts": false },
    "coverage_note": "3 partner account(s) excluded from patterns (their staff attend co-hosted events, which inflates engagement signals — HEY-1735). Pass include_partner_accounts=true to include them, labeled account_role='partner'."
  }
}

Response field reference

Envelope

Field	Type	Description
`tool`	string	Always `"get_cross_event_patterns"`.
`result_count`	integer	Number of accounts returned (after `min_events` filter, `limit` cap, and partner exclusion).
`data`	array	One object per qualifying account.
`metadata.coverage_note`	string \| null	Non-null when one or more partner accounts were excluded by the default `include_partner_accounts=false` — tells you how many and why.

`data[i]`

Field	Type	Description
`company`	string	Resolved display name for the account.
`domain`	string \| null	Account’s grouping domain (enrichment-resolved where available).
`account_role`	`"partner"` \| `"external"` \| `null`	Classification against your own Partner list. `null` only in `is_global` (cross-workspace admin) mode, which is not reachable via the standard workspace-scoped API key.
`events`	array of objects	Chronological (oldest first): `{ event_name, channel_id, event_date, attendee_count, checked_in_count, mql, opportunity }`. `attendee_count` is this account’s headcount at that event; `mql`/`opportunity` are `true` if any attendee from this account hit that signal at that event.
`total_events`	integer	`events.length`.
`first_seen` / `last_seen`	string (ISO 8601) \| null	Bounds of this account’s event history in the workspace.
`trajectory`	`"new"` \| `"increasing"` \| `"stable"` \| `"decreasing"`	`"new"` if fewer than 2 events; otherwise compares MQL/opportunity signal density in the first half of the account’s event history vs. the second half.

Errors

Same generic-sanitized-error behavior as every tool on this surface — see get_workspace_overview — Errors. No parameter here can trigger a validation failure; an unmatched domain filter simply returns result_count: 0 with no coverage_note.

Pagination and limits

No cursor-based pagination. limit (default 20, clamped to [1, 500]) caps the number of accounts returned, applied server-side after sorting by event count then recency — there is no way to fetch “the next 20” beyond raising limit. If you need a specific account regardless of rank, use the domain filter or call get_account_relationship directly.

get_account_relationship — full profile for one account this tool surfaces.
get_workspace_overview — program orientation and integration status. It no longer carries a trajectory rollup of its own (HEY-1913 removed engagement_health), and its suggested_first_queries routes trajectory questions here.
query_event_intelligence — a lighter-weight, contact-inclusive alternative when you want attendee detail, not trajectory classification. Deprecated and being retired (HEY-1895) — prefer this tool or get_account_relationship in new work.

Getting Started

Connecting Your Platforms

MCP Tool Reference

Features

Lists

Partner Ecosystem

If You've Been Invited

Concepts

Frequently Asked Questions

get_cross_event_patterns

Purpose

When to use this

Parameters

Default behavior

Sample request

Sample response

Response field reference

Envelope

`data[i]`

Errors

​Purpose

​When to use this

​Parameters

​Default behavior

​Sample request

​Sample response

​Response field reference

​Envelope

​data[i]

​Errors

​Pagination and limits

​Related tools

Purpose

When to use this

Parameters

Default behavior

Sample request

Sample response

Response field reference

Envelope

`data[i]`

Errors

Pagination and limits

Related tools