> ## 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_account_relationship > Everything heyBTW knows about one account: its event history, contacts, warm intro paths, trajectory and CRM pipeline. > [!NOTE] > > Read-only. The marketer's question is "what is our history with this company?" Reach for this tool before a meeting, an intro ask or an invite decision about one account. Follows the [heyBTW MCP rules](https://heybtw.com/docs/mcp/rules.md). > [!NOTE] > > This page documents the v1 response, the one served by default. The tool is evolving and this page will be revised. ## When to use it * "What's our history with Beacon Hill Software?" * "Who from Beacon Hill has come to our events, and did they check in?" * "Is there a partner who can intro us to them?" * "Before my call, how engaged is this account?" ## Parameters | Parameter | Type | Required | Notes | | - | - | - | - | | `domain` | string | One of `domain` or `account_name` | Preferred, for example `beaconhillsw.com`. | | `account_name` | string | See above | Fallback when you have no domain. | | `limit` | integer | No | Signup history rows read. Default 50, maximum 500. | | `contract_version` | string | No | Omit for v1. Only v1 is advertised. | Archived and demo collabs are excluded, as in list\_events; a restored collab's records return. ## Response `data[0]`: | Field | Meaning | | - | - | | `domain`, `company` | The account. | | `trajectory` | The account's engagement direction across events. | | `event_history[]` | Per event: `event_name`, `channel_id`, `event_date`, `role`, `attendee_count` (sign-ups), `mql`, `opportunity`. | | `contacts[]` | Collapsed to each contact's most recent event: `email`, `name`, `title`, `seniority`, `funnel_status`, `attendance_status`, `source`, `company_domain`, `event_date`, `channel_id`, `partner_source`. | | `contacts_total`, `contacts_shown` | Disclose a cut. | | `warm_intro_paths[]` | Partners with a path into the account, each with `reasons` (`code` and `basis`: co\_attendance, then opportunity\_history, meeting\_history, mql\_history when observed). | | `context_graph_summary` | `narrative`, `trajectory`, `recommended_actions` (fixed rules over roster facts, nothing weighted). | | `agent_guidance` | `crm_joined`, `crm_join_key` (`domain`), `suggested_follow_up`. `crm_enriched` is deprecated: read `crm_joined`. | | `pipeline` | Present when a CRM is connected inside heyBTW: revenue, sourced, influenced, won, opportunity and closed-lost counts. | Contact `source` is `event_attendance` (on an event roster) or `crm_deal_contact` (named on an attributed CRM deal without attending; email, title and funnel\_status are null, never fabricated). `attendance_status` keeps the layers apart: APPROVED is registered, only CHECKED\_IN is attended. A real response for a ScaleUp.ai fixture account, trimmed to two events, two contacts and one coverage note: ```json theme={null} { "tool": "get_account_relationship", "data": [ { "domain": "beaconhillsw.com", "company": "Beacon Hill Software", "trajectory": "stable", "event_history": [ { "event_name": "ScaleUp.ai x Partners: SF Tech Week Open House", "channel_id": "cmvifxnzh000907l2zptjqszl", "event_date": "2026-11-10T01:30:00", "role": "attendee", "attendee_count": 1, "mql": false, "opportunity": false }, { "event_name": "ScaleUp.ai Field Dinner: Austin", "channel_id": "cmvifxsyp000j07l2hmp06n1u", "event_date": "2026-09-27T23:30:00", "role": "attendee", "attendee_count": 2, "mql": false, "opportunity": false } ], "contacts": [ { "email": "hollis.quigley@beaconhillsw.com", "name": "Hollis Quigley", "title": "Head of Growth", "seniority": "executive", "funnel_status": "registered", "attendance_status": "APPROVED", "source": "event_attendance", "company_domain": "beaconhillsw.com", "event_date": "2026-11-10T01:30:00", "channel_id": "cmvifxnzh000907l2zptjqszl", "partner_source": null }, { "email": "rosa.rasmussen@beaconhillsw.com", "name": "Rosa Rasmussen", "title": "Head of Sales Development", "seniority": "executive", "funnel_status": "registered", "attendance_status": "CHECKED_IN", "source": "event_attendance", "company_domain": "beaconhillsw.com", "event_date": "2026-09-27T23:30:00", "channel_id": "cmvifxsyp000j07l2hmp06n1u", "partner_source": null } ], "contacts_total": 5, "contacts_shown": 5, "warm_intro_paths": [], "context_graph_summary": { "narrative": "Beacon Hill Software has attended 3 event(s). 5 senior contact(s) engaged (e.g. Head of Growth level). $86,000 pipeline identified (won).", "trajectory": "stable", "recommended_actions": [] }, "agent_guidance": { "crm_enriched": true, "suggested_follow_up": ["Check the connected CRM for open opportunities"], "crm_joined": true, "crm_join_key": "domain" }, "pipeline": { "company": "beaconhillsw.com", "revenue": 86000, "sourced_revenue": 86000, "influenced_revenue": 0, "won_revenue": 86000, "opportunity_count": 1, "is_won": true, "closed_lost_revenue": 0, "closed_lost_count": 0 } } ], "metadata": { "coverage_notes": [ "partner_source is the partner that canonical attribution credits for the sign-up, read from the account-scoped attribution projection. That projection covers sign-ups whose email is at the account's domain (on a lookup by account_name, sign-ups whose company is that name) and the account's CRM deal contacts. A null partner_source does not mean no partner brought the contact: either no partner is credited for that sign-up, or the sign-up is outside that projection, for example a personal address matched to this account by enrichment." ], "contract_version": "v1" }, "status": "partial", "gaps": [ { "code": "partial_coverage", "message": "Partner events restricted by the host's Sponsor Mode", "retryable": false } ] } ``` ## Rules the agent must follow * `attendee_count` counts sign-ups, never attendance. Only CHECKED\_IN is attended. * A null `partner_source` does not mean no partner brought the contact. Relay the coverage note as written. * When more history exists than `limit` reads, warm path `reasons` and `recommended_actions` are null (unknown, not empty) and a `scope_truncated` gap names the lever. * For owners, open deals and activity, use the user's own CRM connector first, joined on `company_domain`. Say `pipeline` is heyBTW's only when `crm_joined` is true. * Never weight or rank contacts. Serve the facts with their basis. ## Errors and gaps | Code | When | What to do | | - | - | - | | `scope_truncated` (not retryable) | History cut at `limit`. | Raise `limit` up to 500. | | `partial_coverage` (not retryable) | Workspace-wide disclosure, such as partner events restricted by the host's Sponsor Mode. | A disclosure, not a failure. | | `invalid_parameter` | Neither `domain` nor `account_name`. | Provide one. | | `rate_limit_exceeded`, `internal_error` | | Honor Retry-After; retry once on internal\_error. | No cursor is emitted: narrow the query rather than paging. ## Related * [get\_cross\_event\_patterns](https://heybtw.com/docs/tools/get-cross-event-patterns.md): patterns across many accounts. * [get\_partner\_overlaps](https://heybtw.com/docs/tools/get-partner-overlaps.md): which partners share this account. * [get\_event\_attribution](https://heybtw.com/docs/tools/get-event-attribution.md): event-level revenue. * Playbook: [What each system knows](https://heybtw.com/docs/playbooks/what-each-system-knows.md). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.