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

> One collab's ABM plan: which accounts the team targets, who covers each, outreach marks, and seats to goal.

> [!NOTE]
>
> Read-only.

The marketer's question is "who are we going after for this event, who owns each account, and how many seats are left?" Reach for this tool whenever the user asks who is Wishlist or Target, who is covered or uncovered, or the seats to goal for a collab. Never rebuild the plan from chat history or ask the user to paste the ABM table.

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

## When to use it

* "How many seats are left for the SF open house?"
* "Which Target accounts have no owner yet?"
* "Who on the partner side covers Beacon Hill?"
* "How far down the outreach ladder are we on Wishlist accounts?"

## Parameters

| Parameter | Type | Required | Notes |
| - | - | - | - |
| `channel_id` | string | One of `channel_id` or `event_name` | From list\_events. |
| `event_name` | string | See above | An ambiguous name returns no plan and lists the candidates. |
| `cursor` | string | No | `metadata.pagination.next_cursor` for the SAME collab. Expires after 15 minutes. |
| `contract_version` | string | No | Omit for v1. Only v1 is advertised. |

No `limit`: a page holds up to 100 accounts, in the List's own order.

## Response

`data[0]`, read through the same read the ABM board uses, so every value is the board's:

| Field | Meaning |
| - | - |
| `collab` | `channel_id` and `event_name`. |
| `working_from` | `list_id` and `list_name` of the List the plan works from, or null when it has none. |
| `seats_to_goal` | The board's Seats-to-Goal ledger (below). |
| `outreach_ladder` | The collab's outreach marks, in order. |
| `accounts[]` | One page of the working List. |
| `account_total` | The List's members. |
| `agent_guidance` | `scope_boundaries` and `working_list`. |

`seats_to_goal`:

| Field | Meaning |
| - | - |
| `rsvp_target` | The event's RSVP target. |
| `account_count` | Accounts on the plan. |
| `invited`, `registered`, `attended` | Counts of the contacts tracked on the plan. Registered and attended are separate layers. |
| `whitespace` | The board's whitespace count, served as the board computes it. |
| `by_owner[]` | The same counts per owner you may see. An account with several owners counts under each. |

Each account: `company_name` (or null), `company_domain`, `priority` (YOUR workspace's own label, such as Wishlist, Target or General, or null), `covered_by` (owners you may see: kind `you`, `workspace` or `unmanaged_partner` with company name and domain, or `person` with `contact.contact_email` and `contact.contact_name` for a partner's CSM or AM), `owner_count` (every owner, including ones not named to you), `outreach` (contacts per outreach mark), `outreach_unmarked`, `source` (`added`, `matched` or `via_partner`) and `contributed_by`.

A real response for the SF open house fixture, trimmed to the notes that matter. This collab's ABM board has no working List yet, so there are no accounts, but `seats_to_goal` still carries the RSVP target:

```json theme={null}
{
  "tool": "get_abm_plan",
  "result_count": 1,
  "data": [
    {
      "collab": {
        "channel_id": "cmvifxnzh000907l2zptjqszl",
        "event_name": "ScaleUp.ai x Partners: SF Tech Week Open House"
      },
      "working_from": null,
      "seats_to_goal": {
        "rsvp_target": 150,
        "account_count": 0,
        "invited": 0,
        "registered": 0,
        "attended": 0,
        "whitespace": 0,
        "by_owner": []
      },
      "outreach_ladder": [],
      "accounts": [],
      "account_total": 0,
      "agent_guidance": {
        "scope_boundaries": [
          "Overlap facts and counts between this plan and a partner's accounts belong to get_partner_overlaps. This tool never reports them.",
          "Follow-up tasks committed on this collab belong to get_due_tasks.",
          "Invites are sent only through activate_list, with its preview and confirmation steps. This tool sends nothing."
        ],
        "working_list": "Pass working_from.list_id to get_lists to read the working List's members, or to activate_list to send it."
      }
    }
  ],
  "metadata": {
    "coverage_notes": [
      "seats_to_goal is the Seats-to-Goal ledger the ABM board shows: the event's RSVP target and the registered and attended counts of the contacts tracked on the plan. by_owner lists the owners your workspace may see, and an account with several owners counts under each of them.",
      "This collab's ABM surface works from no List yet, so the plan has no accounts. seats_to_goal still shows the event's RSVP target."
    ],
    "contract_version": "v1",
    "pagination": { "limit": 100, "returned": 0, "has_more": false, "next_cursor": null }
  },
  "gaps": [
    { "code": "partial_coverage", "message": "Partner events restricted by the host's Sponsor Mode", "retryable": false }
  ],
  "status": "partial"
}
```

## Rules the agent must follow

* `priority` is the user's own label, not heyBTW's judgment. This tool ranks and recommends nothing.
* A row names no contact to invite: who to invite is the covering owner's decision.
* It reports no overlap and no other partner's priority. For overlap use [get\_partner\_overlaps](https://heybtw.com/docs/tools/get-partner-overlaps.md).
* Read `seats_to_goal` as served. Never compute seats left from other counts.
* Pages are offset-derived: an account added or removed while you page can repeat or skip. De-duplicate on `company_domain`.

## Errors and gaps

| Code | When | What to do |
| - | - | - |
| `invalid_parameter` | Neither `channel_id` nor `event_name`, a malformed id, or a cursor not issued for this call. | Fix it. |
| `entity_not_found` | No collab this workspace hosts or partners on with active consent. | Check list\_events. |
| `query_timeout` | A dynamic working List could not be evaluated in time. | Retry later. |
| `upstream_crm_error` | The CRM did not answer for a working List whose criteria need it. | Retry later. |
| `rate_limit_exceeded`, `internal_error` | | Honor Retry-After; retry once on internal\_error. |

A failed read is always an error, never an empty plan.

## Related

* [get\_lists](https://heybtw.com/docs/tools/get-lists.md): the working List's members.
* [activate\_list](https://heybtw.com/docs/tools/activate-list.md): send the working List, with preview and confirmation.
* [get\_partner\_overlaps](https://heybtw.com/docs/tools/get-partner-overlaps.md): overlap facts.
* Playbook: [Invite sprint](https://heybtw.com/docs/playbooks/invite-sprint.md).


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