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

> One compact fact row per account for 1 to 200 domains in one call, or a filtered page of the workspace's accounts.

get\_accounts is the batch account read. Give it up to 200 company domains and it returns one row per domain, in your order, from a precomputed rollup. Call it whenever you build, format or filter an account list (invite planning, ABM, an account import, "which of these 80 accounts have we met") instead of looping [get\_account\_relationship](https://heybtw.com/docs/tools/get-account-relationship.md), which is the deep read for one account.

It reads only your own workspace's events. It never calls a CRM, an enrichment or a partner workspace's data.

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

## When to use it

* "Which of these 80 target accounts have we met at an event?"
* "Show me every account that came to two or more events since July."
* "Which accounts in Austin did a partner bring?"
* "What changed in our account list since yesterday?"

## Parameters

Use one of two modes. `domains` cannot be combined with a filter.

| Parameter | Type | Required | Notes |
| - | - | - | - |
| `domains` | string\[] | Domain mode | 1 to 200 company domains, any order. One row comes back per domain, in your order. An unknown domain is a row with `identity: "unmatched"`. |
| `min_events` | integer | No (filter mode) | Accounts seen at this many events or more. |
| `seen_since` | string | No (filter mode) | `YYYY-MM-DD`. Accounts whose last event is on or after it. |
| `city` | string | No (filter mode) | An event city. |
| `partner` | string | No (filter mode) | A co-host's name. |
| `relationship` | string | No (filter mode) | `partner`. |
| `in_target` | boolean | No (filter mode) | Accounts in, or not in, the workspace's target. |
| `limit` | integer | No (filter mode) | Default 100, maximum 500. |
| `cursor` | string | No (filter mode) | From the previous page. |
| `since` | string | No | An ISO 8601 timestamp, the previous response's `next_since`. Returns only the accounts whose facts changed after it. |
| `contract_version` | string | No | Omit for v1, the only version advertised. |

## Response

Each row:

| Field | Meaning |
| - | - |
| `company_domain` | The join key. |
| `identity` | `matched` or `unmatched`. |
| `company` | The company's name. |
| `relationship` | The account's relationship to the workspace. |
| `in_target` | Whether the account is in the workspace's target. |
| `events_count` | How many of your events the account appears at. |
| `event_cities` | The cities of those events, in event order. |
| `first_seen`, `last_seen` | The first and last event dates. |
| `people_count` | People at the account that heyBTW holds. |
| `people_attended_count` | Of those, people who attended. |
| `titles_sample` | Up to 5 titles. |
| `partners` | The co-hosts on its events. |
| `known_by` | The workspace members who know someone there. |
| `invited_count` | People at the account who were invited. |
| `open_deal` | Always null here. See the carry block. |
| `rollup_as_of` | When the rollup was built. |
| `via` | Always `heybtw`. |
| `fact_id` | The stable id to cite the fact. |

`data[0].counts` holds `matched`, `unmatched`, `seen_before` (accounts with someone who attended), `at_target`, `with_partner` and `with_known_by` over the served rows.

`data[0].carry` names the join key (`company_domain`) and the question a CRM connector the user has in Claude answers. No CRM is called, which is why `open_deal` is null.

Nothing here is a ranking, tier or engagement metric. You rank.

## Freshness

The rollup is rebuilt every 15 minutes, so `rollup_as_of` can be up to 15 minutes behind heyBTW's own records.

## Delta sync

Pass `since` with the previous response's `next_since` to get only the accounts whose facts changed after it. An account that no longer qualifies reads `change: "removed"`. Every response served with `since` carries `next_since`.

A `since` older than the change history kept is refused with `invalid_parameter`, never answered with a partial delta. Call again without `since`.

## Rules the agent must follow

* Use get\_accounts for a list of accounts and get\_account\_relationship for one account in depth. Never loop the deep read over a list.
* For deals, owners and activity, ask the user's own CRM connector, joined on `company_domain`. Do not write the answer back into heyBTW.
* An `unmatched` row means heyBTW holds no event history for that domain. It is not a zero.
* Per-person rows come from [get\_relationship\_ledger](https://heybtw.com/docs/tools/get-relationship-ledger.md), and a person check from [check\_people](https://heybtw.com/docs/tools/check-people.md).

## Limits

One call is one request however many domains it names. `limit` applies in filter mode only. See [Limits and errors](https://heybtw.com/docs/mcp/limits-and-errors.md).

## Errors and gaps

* `invalid_parameter`: a domain, filter, `since` or `cursor` is malformed, a `since` is past the change history, or `domains` was combined with a filter.
* `rate_limit_exceeded`: wait for `Retry-After`.
* `internal_error`: retry once.

A read-scoped sign-in is enough. No write access is needed.

## Related

* [get\_account\_relationship](https://heybtw.com/docs/tools/get-account-relationship.md): one account in depth.
* [get\_relationship\_ledger](https://heybtw.com/docs/tools/get-relationship-ledger.md): one row per person per event.
* [check\_people](https://heybtw.com/docs/tools/check-people.md): what the workspace knows about a list of people.
* [Works with any CRM](https://heybtw.com/docs/playbooks/works-with-any-crm.md): joining these rows to your CRM.


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