> ## 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

> What each partner's events produced: sourced and influenced revenue, funnel counts, seniority and account coverage per partner.

> [!NOTE]
>
> Read-only.

The marketer's question is "what did this partner actually drive?" This is the one tool for partner-level revenue. Reach for it for a partner rollup across events; for one event's view use [get\_event\_attribution](https://heybtw.com/docs/tools/get-event-attribution.md). Both read the same canonical resolver, so their partner figures reconcile.

Follows the [heyBTW MCP rules](https://heybtw.com/docs/mcp/rules.md).

## When to use it

* "How much pipeline did Brightpath drive this quarter?"
* "Which partners brought senior people, not just sign-ups?"
* "What's our account coverage with Ferrocity?"
* "Prep the partner QBR numbers."

## Parameters

| Parameter | Type | Required | Notes |
| - | - | - | - |
| `partner_domain` | string | No | Substring match, so `acme` can match acme.com and acmecorp.io. |
| `partner_name` | string | No | Substring match on the partner name. |
| `time_range` | string | No | `last_30_days`, `this_quarter`, `last_quarter`, `ytd`, `program_total` (default). Anchored to the collab's event date, not deal creation. An unrecognized value applies no bound. |
| `include_archived` | boolean | No | Default false. Widens only the partner-record filter; archived and demo collabs stay excluded. |
| `contract_version` | string | No | Omit for v1. Only v1 is advertised. |

## Response

`crm_context` comes first (capability `deal_read`). Then one row per identity-resolved partner, ordered by sourced revenue descending, then total sourced, then partner name; an unknown value sorts last (`metadata.ordering`).

| Field | Meaning |
| - | - |
| `partner_name`, `partner_domain`, `partner_identity_key`, `source_partner_ids` | Partners sharing a canonical domain are one row. |
| `event_count`, `event_names` | Events in the window. |
| `reasons[]` | Structured facts, each a `code` and its `basis`: `event_participation` (event\_count), then opportunity\_history, meeting\_history, mql\_history when observed. Null (not `[]`) when activity rows were truncated. |
| `sourcing_breakdown` | `total_sourced`, `by_event`. |
| `funnel_metrics` | `total_signups`, MQL, opportunity and meeting counts and rates. |
| `seniority_profile` | Counts of the contacts the partner brought, with sample size. |
| `contacts[]`, `contacts_total`, `contacts_shown`, `contacts_has_more` | A contact sample. |
| `pipeline_impact` | `sourced_revenue`, `influenced_revenue`, `influenced_new_revenue`, `influenced_expansion_revenue`, `won_revenue`, `company_count`, `opportunity_count`, `crm_joined`, `crm_join_key`. |
| `account_overlap` | The same numbers the Partner Ecosystem dashboard Coverage cards show: `portfolio_reached`, `penetration`, `co_marketing_events`, `multi_touch`, `never_reached`, `unclassified`, `icp_scoped`, `denominator_mode`, `upcoming`. |
| `custom_list_overlays[]` | Custom Lists attributed to the partner's domain. `[]` is normal. |
| `trends` | `this_quarter_vs_last_quarter.events_cohosted_delta`, for a single matched partner only. |

In `pipeline_impact`, null means unavailable and 0 means measured, none. `account_overlap` is null when the query is cross-workspace, when the partner spans more than one collab in this workspace, or when the coverage lookup failed soft. None of those means "no data".

> [!NOTE]
>
> `influenced_new_revenue` and `influenced_expansion_revenue` come from the dashboard's Influence Breakdown panel ("Partner Influenced (New)" and "Partner Influenced (Expansion)"). That taxonomy is independent of Sourced and Influenced: the two classifiers disagree deal by deal. Never present these dollars as a slice of `influenced_revenue`, never expect them to sum to it, and never add them to the headline. The panel's other buckets (Direct, Direct Influenced, Partner Sourced) are not served here; say the split is unavailable. The mapping is in `agent_guidance.dashboard_vocabulary` on [get\_workspace\_overview](https://heybtw.com/docs/tools/get-workspace-overview.md).

A real response from the ScaleUp.ai fixtures, trimmed to one of four partners:

```json theme={null}
{
  "tool": "get_partner_insights",
  "result_count": 4,
  "crm_context": {
    "connection_path": "dashboard",
    "provider": "attio",
    "status": "connected",
    "capability": "deal_read",
    "capability_served": true,
    "crm_joined": true,
    "crm_join_key": ["email", "company_domain"]
  },
  "data": [
    {
      "partner_name": "Ferrocity",
      "partner_domain": "ferrocity.ai",
      "partner_identity_key": "domain:ferrocity.ai",
      "source_partner_ids": ["cmvifydub001707l2aimx9q8a"],
      "event_count": 1,
      "event_names": ["ScaleUp.ai x Partners: SF Tech Week Open House"],
      "reasons": [{ "code": "event_participation", "basis": "EventSignUp.partnerSource", "event_count": 1 }],
      "status": "Active",
      "sourcing_breakdown": { "total_sourced": 0, "by_event": [] },
      "funnel_metrics": { "total_signups": 0, "mql_count": 0, "opportunity_count": 0, "meeting_count": 0, "mql_rate": 0.0, "opportunity_rate": 0.0, "meeting_rate": 0.0 },
      "contacts": [],
      "contacts_total": 0,
      "pipeline_impact": {
        "sourced_revenue": 0,
        "influenced_revenue": 0,
        "influenced_new_revenue": 0,
        "influenced_expansion_revenue": 0,
        "won_revenue": 0,
        "company_count": 0,
        "opportunity_count": 0,
        "crm_joined": true,
        "crm_join_key": "company_domain"
      },
      "account_overlap": {
        "portfolio_reached": { "reached": 0, "total": 0 },
        "penetration": { "pct": 0, "trendPct": null },
        "co_marketing_events": 0,
        "multi_touch": 0,
        "never_reached": 0,
        "unclassified": 0,
        "icp_scoped": 0,
        "denominator_mode": "raw",
        "upcoming": 0
      },
      "custom_list_overlays": [],
      "trends": null
    }
  ],
  "metadata": {
    "contract_version": "v1",
    "ordering": "sourced_revenue_desc_then_total_sourced_desc_then_partner_name_asc"
  },
  "status": "partial",
  "gaps": [
    { "code": "partial_coverage", "message": "Partner events restricted by the host's Sponsor Mode", "retryable": false }
  ]
}
```

`pipeline_impact.crm_enriched` is also emitted; it is deprecated and will be removed on 2026-11-16. Read `crm_joined`.

## Rules the agent must follow

* Partner revenue comes from this tool only. Never compute a partner figure yourself.
* Say a revenue figure is heyBTW's only when `pipeline_impact.crm_joined` is true.
* Null is unknown, never zero. A null `reasons` or `account_overlap` is withheld, not empty.
* No rank or engagement composite is served. Ordering is by sourced revenue only.
* Quote dashboard words from `dashboard_vocabulary` so the user can find the figure on screen.

## Errors and gaps

| Code | When | What to do |
| - | - | - |
| `canonical_attribution_unavailable` (retryable) | The canonical resolver was unreachable. Revenue fields degrade to null. | Retry; never fill in a number. |
| `partial_coverage` (not retryable) | Canonical data missing for named records, or workspace-wide disclosures. | Relay as written. |
| `scope_truncated` (not retryable) | Partner activity rows capped at 500. | Narrow with `partner_name`, `partner_domain` or `time_range`. |
| `rate_limit_exceeded`, `internal_error` | | Honor Retry-After; retry once on internal\_error. |

## Related

* [get\_event\_attribution](https://heybtw.com/docs/tools/get-event-attribution.md): event-scoped revenue and partners.
* [get\_partner\_overlaps](https://heybtw.com/docs/tools/get-partner-overlaps.md): accounts shared with partners.
* [get\_workspace\_overview](https://heybtw.com/docs/tools/get-workspace-overview.md): `crm_context` and `dashboard_vocabulary`.
* Playbook: [Follow-up and ROI](https://heybtw.com/docs/playbooks/follow-up-and-roi.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.