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.
Response
Each row: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, sorollup_as_of can be up to 15 minutes behind heyBTW’s own records.
Delta sync
Passsince 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
unmatchedrow means heyBTW holds no event history for that domain. It is not a zero. - Per-person rows come from get_relationship_ledger, and a person check from check_people.
Limits
One call is one request however many domains it names.limit applies in filter mode only. See Limits and errors.
Errors and gaps
invalid_parameter: a domain, filter,sinceorcursoris malformed, asinceis past the change history, ordomainswas combined with a filter.rate_limit_exceeded: wait forRetry-After.internal_error: retry once.
Related
- get_account_relationship: one account in depth.
- get_relationship_ledger: one row per person per event.
- check_people: what the workspace knows about a list of people.
- Works with any CRM: joining these rows to your CRM.