> ## Documentation Index > Fetch the complete documentation index at: https://heybtw.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # get_cross_event_patterns > Multi-event account engagement trajectories — which companies are deepening engagement across your events over time. 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](/docs/integrations/mcp-tools#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`](/docs/mcp-tools/get-account-relationship) for the ones worth a deeper look. * Feeding `get_workspace_overview`'s `engagement_health` block is this tool's own logic reused at workspace scale — call this tool directly for the account-level detail behind that rollup. ## 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 ```json theme={null} { "tool": "get_cross_event_patterns", "arguments": { "min_events": 2, "limit": 20 } } ``` ## Sample response ```json theme={null} { "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](/docs/mcp-tools/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`](/docs/mcp-tools/get-account-relationship) directly. ## Related tools * [`get_account_relationship`](/docs/mcp-tools/get-account-relationship) — full profile for one account this tool surfaces. * [`get_workspace_overview`](/docs/mcp-tools/get-workspace-overview) — `program_metrics.engagement_health` is a workspace-wide rollup using this tool's trajectory logic. * [`query_event_intelligence`](/docs/mcp-tools/query-event-intelligence) — a lighter-weight, contact-inclusive alternative when you want attendee detail, not trajectory classification.