list_event_contacts
Read-only
The reverse lookup: which contacts triggered one analytics event — achieved a goal (kind GOAL + goalKey), clicked a button (BUTTON_CLICK + blockId, optionally buttonId/buttonIndex), were sent a block (BLOCK_SENT + blockId), or received a broadcast (BROADCAST_DELIVERED + broadcastId). Read-only, paginated, ordered by each contact's most recent matching event. Runs as SQL over the event tables, so it is safe on large workspaces — prefer it over paging list_contacts and checking each one. Omitting goalKey for kind GOAL fails with the list of known goal keys, which is the cheapest way to discover them.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes | Which event defines the audience: GOAL, BUTTON_CLICK, BLOCK_SENT, or BROADCAST_DELIVERED. | |
| page | No | 1-based page number. Defaults to 1. | |
| botId | No | Only contacts of this bot. Omit for all bots in the application. | |
| limit | No | Contacts per page, between 1 and 100. Defaults to 20. | |
| search | No | Case-insensitive substring matched against the contact name, username and platformId. | |
| blockId | No | Required for kind BLOCK_SENT and BUTTON_CLICK. Block id, from get_flow_context or get_block_details. | |
| endDate | No | Only events at or before this time, same format as startDate. Defaults to now. | |
| goalKey | No | Required for kind GOAL. The goal key, e.g. "purchase". | |
| buttonId | No | For kind BUTTON_CLICK: narrow to one button. Format is `cb_{blockId}_{index}` over the block's buttons in editor order. Omit to count a click on any button of the block. | |
| startDate | No | Only events at or after this time (ISO 8601 date string). Applies to every kind; for BROADCAST_DELIVERED the event time is when that contact's delivery was sent. Omit for the whole history — that is what "ever achieved this goal" needs. | |
| broadcastId | No | Required for kind BROADCAST_DELIVERED. Broadcast id, from list_broadcasts. Counts deliveries with status SENT, DELIVERED or READ. | |
| buttonIndex | No | For kind BUTTON_CLICK: alternative to buttonId, the 0-based button position. Ignored when buttonId is set. | |
| applicationId | No | Application (workspace) id. Optional: an application-scoped key (app_...) defaults to its own application, but a personal key (usr_...) has no default and omitting it fails with MCP_APPLICATION_REQUIRED. Call list_applications to get the id. |