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

> The raw record of who from these accounts or people came to which events, one row per person per event.

> [!NOTE]
>
> Read-only.

When you need everyone from a set of accounts, a list of people, or one collab, at every event, in one call, use the ledger. Each row is one person at one event with their status, who brought them, who knows them and their city.

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

## When to use it

* "Show me every event anyone from these 30 target accounts has been to."
* "Which of these people actually checked in, and where?"
* "Give me the LA dinner roster as a CSV with partner source and city."
* "Who from Wavecrest has registered for anything this quarter?"

## Parameters

Give at least one of `domains`, `emails` or `channel_id`.

| Parameter | Type | Required | Notes |
| - | - | - | - |
| `domains` | list of strings | One of three | 1 to 200 company domains. |
| `emails` | list of strings | One of three | 1 to 500 emails. |
| `channel_id` | string | One of three | One of your collabs, from [list\_events](https://heybtw.com/docs/tools/list-events.md). |
| `date_from`, `date_to` | string | No | On the event start. ISO date or timestamp. No default window. |
| `status` | list of strings | No | Any of `invited`, `registered`, `declined`, `cancelled`, `attended`, `no_show`, `unknown`. |
| `limit` | integer | No | Default 200, maximum 1000. |
| `cursor` | string | No | `metadata.pagination.next_cursor` from the previous call with the same filters. |
| `format` | string | No | `json` (default) or `csv`. |
| `include_partner_accounts` | boolean | No | Default false: partners' staff are left out. |
| `include_own_domain` | boolean | No | Default false: your own staff are left out. |
| `contract_version` | string | No | Omit for v1. |

## Response

`data[0]` holds the page of rows and counts over the whole matching set.

| Field | Meaning |
| - | - |
| `row_count`, `total_matching` | Rows on this page, and rows matching the filters. |
| `counts_by_status` | Counts per status over the whole matching set. |
| `columns` | The column order, also used for `format: csv`. |
| `rows[]` | email, company\_domain, company, name, title, seniority, channel\_id, event\_name, event\_start, event\_city, status, invited\_at, registered\_at, checked\_in\_at, partner\_source, known\_by, person\_city, as\_of, via. |
| `csv` | With `format: csv`, the same rows as one CSV string. |

How to read `status`:

* `attended` is a checked-in sign-up. `registered` is an RSVP, never attendance.
* `no_show` appears only for a held event whose source recorded check-in. Where check-in was not recorded the sign-up reads `registered` with a `partial_coverage` gap.
* An event not yet held reads `registered` with a gap.
* `seniority` is advisory, from the title, and used by no rule or count.
* A null `partner_source` does not mean no partner brought the person.

This sample is trimmed from a real call today on a ScaleUp.ai fixture collab.

```json theme={null}
{
  "tool": "get_relationship_ledger",
  "data": [
    {
      "row_count": 1,
      "total_matching": 7,
      "counts_by_status": {
        "invited": 0, "registered": 7, "declined": 0, "cancelled": 0,
        "attended": 0, "no_show": 0, "unknown": 0
      },
      "rows": [
        {
          "email": "luis.castillo@wavecrestgames.com",
          "company_domain": "wavecrestgames.com",
          "company": "Wavecrest Games",
          "name": "Luis Castillo",
          "title": "Head of Partnerships",
          "seniority": "executive",
          "channel_id": "cmvifxr72000e07l2oj1h2be8",
          "event_name": "ScaleUp.ai x Marlowe Cloud: LA Revenue Leaders Dinner",
          "event_start": "2026-11-19T02:30:00",
          "event_city": "Los Angeles-Long Beach-Anaheim, CA",
          "status": "registered",
          "invited_at": null,
          "registered_at": "2026-10-15T23:00:00.000Z",
          "checked_in_at": null,
          "partner_source": null,
          "known_by": ["ben@heybtw.com"],
          "person_city": "Pasadena",
          "as_of": "2026-10-21T18:24:54.916Z",
          "via": "heybtw"
        }
      ]
    }
  ],
  "metadata": {
    "pagination": { "limit": 1, "returned": 1, "has_more": true, "next_cursor": "v1.eyJ..." }
  },
  "gaps": [
    {
      "code": "partial_coverage",
      "message": "Event field not recorded: status",
      "what_to_do": "Treat registered on those events as an RSVP, not attendance. Retrying will not change the result until the event is held.",
      "retryable": false
    }
  ],
  "status": "partial"
}
```

## Rules the agent must follow

* Registered is not attended. Only `attended` (checked in) means the person came.
* Null is unknown, never zero.
* Nothing here is a ranking or engagement metric. Do not grade people from it.
* Page with `next_cursor` on the same filters; do not fan out per-event get\_event\_details calls instead.
* No row reads `cancelled` today, because no store records a cancelled registration.

## Errors and gaps

* `invalid_parameter`: none of `domains`, `emails` and `channel_id` was given, or a filter, limit or cursor is malformed.
* `partial_coverage` gap: an event not yet held, or check-in not recorded. Not retryable. Disclose it.
* `entitlement_required`: the plan lacks MCP read.
* `internal_error`: retry once.

## Related

* [get\_account\_relationship](https://heybtw.com/docs/tools/get-account-relationship.md): one account, contacts collapsed to their most recent event.
* [get\_event\_details](https://heybtw.com/docs/tools/get-event-details.md): one event's roster and attendance mix.
* [check\_people](https://heybtw.com/docs/tools/check-people.md): what the workspace knows per email, before an import.
* Playbook: [Did anyone follow up, and what did the event do for pipeline](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.