list_events

Read-only.

The event directory. It answers “which events do we have, and which are coming up?” An agent calls it whenever it needs to enumerate events or find the channel_id another tool takes. Follows the heyBTW MCP rules.

When to use it

“What events do we have coming up?”
“Which events did we run last quarter?”
“Is anything happening today?”
“What’s the channel_id for the Austin dinner?”
“How many people signed up for each event?”

Parameters

All optional. No filter means every event; there is no default time window.

Parameter	Type	Required	Notes
`status`	string	No	`upcoming`, `live` or `past`: the event’s side of its event day on the collab’s calendar. `live` is every event whose day is today.
`date_from`	string	No	Inclusive lower bound on the event start. `YYYY-MM-DD` (a whole UTC day) or `YYYY-MM-DDTHH:MM[:SS]` with an optional `Z` or `+HH:MM` offset. Other forms are refused.
`date_to`	string	No	Inclusive upper bound on the event start, same grammar.
`contract_version`	string	No	Omit for `v1`.

There is no limit and no cursor. Narrow with status or dates instead of paging.

Response

One row per event in program scope. Archived and demo collabs are excluded, the same set get_event_attribution reads. With no filter, rows come newest first (metadata.ordering: event_date_desc_then_channel_id); with status: upcoming they come soonest first.

Field	Meaning
`event_name`	The name other tools accept as `event_name`.
`channel_id`	The collab handle. Pass it to `get_event_details` and the other per-event tools.
`event_date`	The event START. A collab with no start set reads its stored start, and a gap names it.
`event_tense`	`upcoming`, `live`, `past` or `unscheduled`. Same clock as `get_event_details`.
`format`	`in_person`, `virtual`, `hybrid` or `unknown`. Never assumed.
`roster_count`	Sign-up records. Equals `attendance.total` in `get_event_details`. It is not attendance.
`crm_joined`, `crm_join_key`	Always `false` and `null`: a directory row carries no CRM value.
`crm_enriched`	Deprecated, removed on 2026-11-16. Read `crm_context` from `get_workspace_overview` instead.

The sample below is trimmed from a real status: "upcoming", date_from: "2026-11-01" call.

{
  "tool": "list_events",
  "result_count": 2,
  "data": [
    {
      "event_name": "ScaleUp.ai x Partners: SF Tech Week Open House",
      "channel_id": "cmvifxnzh000907l2zptjqszl",
      "event_date": "2026-11-10T01:30:00+00:00",
      "event_tense": "upcoming",
      "format": "in_person",
      "roster_count": 73,
      "crm_enriched": true,
      "crm_joined": false,
      "crm_join_key": null
    },
    {
      "event_name": "ScaleUp.ai x Marlowe Cloud: LA Revenue Leaders Dinner",
      "channel_id": "cmvifxr72000e07l2oj1h2be8",
      "event_date": "2026-11-19T02:30:00+00:00",
      "event_tense": "upcoming",
      "format": "in_person",
      "roster_count": 7,
      "crm_enriched": true,
      "crm_joined": false,
      "crm_join_key": null
    }
  ],
  "metadata": {
    "date_range_applied": "2026-11-01T00:00:00.000Z to any",
    "filters_applied": { "status": "upcoming", "date_from": "2026-11-01T00:00:00.000Z", "date_to": null },
    "contract_version": "v1",
    "ordering": "event_date_asc_then_channel_id"
  },
  "status": "partial",
  "gaps": [
    {
      "code": "partial_coverage",
      "message": "Partner events restricted by the host's Sponsor Mode",
      "what_to_do": "Use the heyBTW dashboard's partner view for those events. Retrying will not change the result.",
      "retryable": false
    }
  ]
}

event_date is UTC. The SF open house starts at 01:30 UTC on 10 November, which is the evening of 9 November in its own time zone. Read the event day from get_event_details (goal.clock.event_date), not from this timestamp.

Rules the agent must follow

Report roster_count as sign-ups, never as attendance. For who came, call get_event_details and read attendance.attended.
Read event_tense as served. Never work it out from event_date and today’s date.
This is a directory, not a metrics tool. It carries no revenue, pipeline or funnel field. For revenue use get_event_attribution.
Use channel_id from these rows; do not guess one.

Errors and gaps

Code	What it means	What to do
`partial_coverage` (Sponsor Mode)	Partner events restricted by the host’s Sponsor Mode are not listed. `retryable: false`.	List what was served and say the rest are on the dashboard’s partner view.
`invalid_parameter`	A date outside the accepted grammar (for example `11/01/2026`) or an unknown `status`.	Rewrite the date as `YYYY-MM-DD` and call again.
`internal_error`	Failure on heyBTW’s side.	Retry once.
`rate_limit_exceeded`	Over the per-workspace window.	Wait for `Retry-After`.

get_event_details: one event’s roster, attendance and goal.
get_event_attribution: revenue per event.
get_workspace_overview: program totals over the same set of events.
Playbooks: The morning after, Invite sprint.

Get started

How heyBTW MCP works

Playbooks

Tools: orientation

Tools: events and rosters

Tools: people and invites

Tools: after the event

Tools: accounts and partners

Tools: pipeline

When to use it

Parameters

Response

Rules the agent must follow

Errors and gaps

​When to use it

​Parameters

​Response

​Rules the agent must follow

​Errors and gaps

​Related

When to use it

Parameters

Response

Rules the agent must follow

Errors and gaps

Related