> ## 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_partner_insights
> Partner influence metrics — sourcing breakdown, seniority profile, funnel rates, and pipeline impact per partner.
This page documents the **Python MCP surface** (`mcp.heybtw.com`). It reflects `mcp-server/tools/partner_insights.py` as of this page's publication — see [Schema stability](/docs/integrations/mcp-tools#schema-stability).
## Purpose
`get_partner_insights` returns one entry per partner with a full sourcing and funnel breakdown: how many signups/MQLs/opportunities/meetings they've driven, per-event detail, a seniority profile of the contacts they've brought, and (when HubSpot is connected) pipeline revenue impact.
## When to use this
* "Which partners have a relationship with a target account we could leverage for a warm intro?" — pair with `get_account_relationship` for a specific account, or scan all partners here first.
* "Which partner should we lean on more — who's actually converting, not just attending?"
* Building a partner performance leaderboard or QBR deck.
## Parameters
| Name | Type | Required | Default | Description | Example |
| ------------------ | ------- | -------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- |
| `partner_name` | string | No | `null` | Filter to partners whose name contains this substring (case-insensitive). | `"Northwind"` |
| `partner_domain` | string | No | `null` | Filter to partners whose domain contains this substring. | `"northwind"` |
| `include_archived` | boolean | No | `false` | Include archived/inactive partner relationships. | `true` |
| `time_range` | string | No | `"program_total"` | One of `last_30_days`, `this_quarter`, `last_quarter`, `ytd`, `program_total`. Scopes `event_count`, `event_names`, `pipeline_impact`, `sourcing_breakdown`, and `funnel_metrics` to the window. `program_total` (or any unrecognized value) applies no bound. | `"this_quarter"` |
**`time_range` windows are anchored to the event's date, not to deal-creation
date.** This tool answers "what did this partner's events produce in this
window", not "what deals were created in this window" — a different question
a CRM-facing tool would answer. Bounds are computed in UTC and carry an
explicit offset on the wire, so parsing is unambiguous; the quarter and year
boundaries themselves are anchored to UTC-now, so a workspace far from UTC
can see a boundary land up to roughly 12 hours off its local one.
## Default behavior
Called with no parameters, returns **every** partner in the workspace (archived ones excluded by default), strongest relationship first — no result cap, no pagination. Every partner entry is included even if they have zero sourced signups (`total_sourced: 0`); filter client-side on `sourcing_breakdown.total_sourced > 0` if you only want active partners.
## Sample request
```json theme={null}
{
"tool": "get_partner_insights",
"arguments": {}
}
```
## Sample response
```json theme={null}
{
"tool": "get_partner_insights",
"query_time_ms": 73.9,
"result_count": 1,
"data": [
{
"partner_name": "Northwind Ventures",
"partner_domain": "northwindventures.example",
"event_count": 3,
"event_names": ["Robotics Summit SF 2026", "Automation Roundtable Q1", "Founders Dinner NYC"],
"status": "active",
"sourcing_breakdown": {
"total_sourced": 46,
"by_event": [
{ "event_name": "Robotics Summit SF 2026", "channel_id": "chn_88af1", "sourced": 22, "mql": 6, "opportunity": 2 },
{ "event_name": "Automation Roundtable Q1", "channel_id": "chn_71c02", "sourced": 14, "mql": 3, "opportunity": 1 },
{ "event_name": "Founders Dinner NYC", "channel_id": "chn_5b901", "sourced": 10, "mql": 2, "opportunity": 0 }
]
},
"funnel_metrics": {
"total_signups": 46,
"mql_count": 11,
"opportunity_count": 3,
"meeting_count": 5,
"mql_rate": 0.2391,
"opportunity_rate": 0.0652,
"meeting_rate": 0.1087
},
"seniority_profile": {
"executive": 2,
"director_plus": 9,
"manager": 14,
"individual_contributor": 18,
"unknown": 3
},
"contacts": [
{
"email": "priya.nair@lighthouserobotics.example",
"name": "Priya Nair",
"title": "VP of Product",
"company": "Lighthouse Robotics",
"seniority": "director_plus",
"funnel_status": "opportunity"
}
],
"contacts_total": 46,
"contacts_shown": 46,
"contacts_has_more": false,
"seniority_profile_sample_size": 46,
"seniority_profile_is_sampled": false,
"pipeline_impact": {
"crm_enriched": true,
"sourced_revenue": 128400.0,
"won_revenue": 42000.0,
"company_count": 19
},
"account_overlap": {
"portfolio_reached": 34,
"penetration": 0.28,
"co_marketing_events": 3,
"multi_touch": 11,
"never_reached": 87,
"unclassified": 4,
"icp_scoped": true,
"denominator_mode": "icp",
"upcoming": 2
},
"custom_list_overlays": [],
"trends": null
}
],
"metadata": {
"data_sources_queried": ["Partner", "Channel", "EventSignUp", "EventAttributionOpportunity"],
"date_range_applied": null,
"filters_applied": { "partner_name": null, "partner_domain": null, "include_archived": false, "crm_enriched": true },
"coverage_note": null
}
}
```
## Response field reference
### Envelope
| Field | Type | Description |
| --------------- | ------- | ----------------------------------------------------------------------------------------------------------------- |
| `tool` | string | Always `"get_partner_insights"`. |
| `query_time_ms` | number | Server-side execution time in ms. |
| `result_count` | integer | Number of partners in `data`. |
| `data` | array | One object per partner, strongest relationship first. |
| `metadata` | object | `coverage_note` is `"Connect HubSpot CRM to unlock pipeline attribution"` when CRM is not connected, else `null`. |
### `data[i]`
| Field | Type | Description |
| ----------------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `partner_name` | string | Partner display name. |
| `partner_domain` | string \| null | Partner domain, when set. |
| `event_count` | integer | Distinct events this partner has been associated with. |
| `event_names` | array of strings | Names of those events. |
| `status` | string \| null | Partner relationship status (e.g. `"active"`), from the `Partner` record. |
| `sourcing_breakdown.total_sourced` | integer | Total signups attributed to this partner across all events. |
| `sourcing_breakdown.by_event` | array of objects | Per-event `{ event_name, channel_id, sourced, mql, opportunity }`. |
| `funnel_metrics` | object | `{ total_signups, mql_count, opportunity_count, meeting_count, mql_rate, opportunity_rate, meeting_rate }`. Rates are `0.0` when `total_signups` is `0`. |
| `seniority_profile` | object | Count of contacts per tier: `executive`, `director_plus`, `manager`, `individual_contributor`, `unknown`. **Built from the returned `contacts` array, so it sums to `contacts_shown`, not `contacts_total`.** When more contacts exist than were returned, this is a sample — see the two flags below before computing a percentage. |
| `seniority_profile_sample_size` | integer | How many contacts the profile was built from. Equals `contacts_shown`. |
| `seniority_profile_is_sampled` | boolean | `true` when contacts were truncated and the profile therefore describes a subset. Do not present a sampled profile as the partner's full seniority mix. |
| `contacts` | array of objects | Up to 50 deduplicated contacts: `{ email, name, title, company, seniority, funnel_status }`. |
| `contacts_total` / `contacts_shown` | integer | Same convention as [`get_account_relationship`](/docs/mcp-tools/get-account-relationship#response-field-reference) — `contacts_shown` is capped at 50. |
| `contacts_has_more` | boolean | `true` when `contacts_total` exceeds `contacts_shown`. |
| `pipeline_impact` | object | `{ crm_enriched: false }` only, when CRM is not connected. When connected: `{ crm_enriched: true, sourced_revenue, won_revenue, company_count }` — dollar amounts summed across every opportunity this partner sourced, `company_count` is distinct companies. |
| `account_overlap` | object \| `null` | `{ portfolio_reached, penetration, co_marketing_events, multi_touch, never_reached, unclassified, icp_scoped, denominator_mode, upcoming }`. The same canonical coverage values the Partner Ecosystem Dashboard's Coverage cards use — never recomputed here. **`null`** for a global/admin call, when the partner spans more than one collab channel (a known gap), or when the internal lookup failed soft. `null` means "not computed", never "no overlap" — do not report it as zero. |
| `custom_list_overlays` | array | One entry per Custom List attributed to this partner. **`[]`** (not `null`) when there is none. `total_members` on an entry is the service-maintained account count, not a fresh count taken at call time. |
| `trends` | object \| `null` | Trend detail for this partner. **`null` unless the call is scoped to a single `partner_domain`** — it is not computed for a whole-workspace listing. Ask for one partner if you need it. |
**The sample above is not a verbatim capture. A live response carries one
more field per partner than it shows.**
Contract v1 is the default — omit `contract_version` and v1 is what you get —
and a v1 partner additionally carries `warmth_score`, a composite between
`event_names` and `status`. It is the **only** field the sample omits;
everything else above is shown as emitted. Contract v2 drops `warmth_score`
and adds an `intro_paths` array of ranked, source-backed paths. v2 is defined
but **not advertised**, so v1 is what a live call returns today.
`warmth_score` is withdrawn (HEY-1897) because it was an unbacked composite,
and it is documented nowhere on this page on purpose. Rank on order, and
compare partners on `sourcing_breakdown` and `funnel_metrics`.
## Errors
Same generic-sanitized-error behavior as every tool on this surface — see [`get_workspace_overview` — Errors](/docs/mcp-tools/get-workspace-overview#errors). This tool has no parameter-validation failure modes of its own; every parameter is optional and any string value is a valid (possibly zero-match) filter.
## Pagination and limits
No caller-facing `limit` parameter and no cursor pagination — every matching partner is returned in one call. Internally, the underlying rows are capped at 500 before aggregation (a fixed server-side safety limit, not adjustable); a workspace would need over 500 partner-event-partnership rows to hit it, well beyond any workspace observed today. `contacts` per partner is separately capped at 50 (see `contacts_shown`/`contacts_total` above).
## Related tools
* [`get_account_relationship`](/docs/mcp-tools/get-account-relationship) — the account-centric view of the same warm-intro data.
* [`get_workspace_overview`](/docs/mcp-tools/get-workspace-overview) — `program_metrics.partner_program` is a workspace-wide rollup of this tool's data.
* [`get_event_details`](/docs/mcp-tools/get-event-details) — per-event partner performance (`partner_performance`), scoped to one event instead of across all events.