> ## 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. # list_events > Which events this workspace has, with each one's channel_id, start date, tense and roster size. > [!NOTE] > > 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](https://heybtw.com/docs/mcp/rules.md). ## 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`](https://heybtw.com/docs/tools/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`](https://heybtw.com/docs/tools/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`](https://heybtw.com/docs/tools/get-workspace-overview) instead. | The sample below is trimmed from a real `status: "upcoming", date_from: "2026-11-01"` call. ```json theme={null} { "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`](https://heybtw.com/docs/tools/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`. | ## Related * [`get_event_details`](https://heybtw.com/docs/tools/get-event-details): one event's roster, attendance and goal. * [`get_event_attribution`](https://heybtw.com/docs/tools/get-event-attribution): revenue per event. * [`get_workspace_overview`](https://heybtw.com/docs/tools/get-workspace-overview): program totals over the same set of events. * Playbooks: [The morning after](https://heybtw.com/docs/playbooks/morning-after.md), [Invite sprint](https://heybtw.com/docs/playbooks/invite-sprint.md). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.