Poll the organization's event log
list_eventsPoll everything that happened: messages, contacts, groups, numbers, quotas.
This is how an agent learns about inbound messages without hosting a webhook endpoint.
Events come back newest first, so polling for new ones uses
ending_before, not starting_after. Typical loop: call with no
cursor and remember the id of the FIRST event in the page (the newest
one); next time, pass that id as ending_before to get only what has
happened since. An empty page means you are caught up.
starting_after does the opposite: it walks BACKWARD into history,
which is what you want for reading a backlog, and never what you want
for noticing something new. Passing the last id you handled to
starting_after in a loop returns steadily older events and never
reaches the present.
request_id returns everything that came of one earlier call. A write
tool's result carries request_id when the platform issued one; keep it
and you can ask later what became of that specific send.
number_id restricts to one number and keeps matching its events after
the number is renamed. number_alias restricts to one inbox by the
alias it had when the event happened, so a rename hides the older
events; the two can be combined. Either one excludes storage.* and
media.unavailable events, which belong to the organization rather
than to any one number.
Most events carry a number_alias telling you which inbox they belong
to, and number_id (num_…), the same number's permanent identifier.
The alias is the one at the time of the event and can be renamed later;
the number_id cannot. You need one of them: message, contact and group
ids are unique but not self-addressing, so an id alone does not tell you
which number's tools to use with it, and both work as number_alias in
the other tools. Read the fields defensively rather than assuming they
are there: storage.* and media.unavailable belong to the
organization as a whole and have no single number to name, so on those
the keys are absent rather than empty.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | How many events to return, 1-100. Defaults to 25. | |
| number_id | No | Restrict results to one number by its `id` (`num_…`, as returned by `list_numbers`). It keeps matching the number's events after the number is renamed, unlike `number_alias`, which matches the alias the number had when the event happened. Can be combined with `number_alias`. Absent means every number. Setting it excludes `storage.*` and `media.unavailable` events, which belong to the organization rather than to any one number. | |
| event_type | No | Filter to exactly one event type, e.g. `message.received`. Common ones: `message.sent`, `message.delivered`, `message.read`, `message.received`, `message.reacted`, `message.edited` (a text or caption edit, or a calendar event that was edited or canceled), `message.calendar_responded` (a guest answered a calendar event), `message.quota.warning`, `number.connected`, `number.disconnected`, `contact.created`, `contact.quota.warning`, `group.joined`, `group.participants_added`. Use `event_types` instead to filter on more than one at once. | |
| request_id | No | Return only the events that came of one earlier call (`req_…`). A write tool's result carries `request_id` when the platform issued one; keep it and you can ask later what became of that send. | |
| created_gte | No | Only events created at or after this instant. ISO 8601 with an offset, e.g. `2026-09-01T00:00:00Z`. | |
| created_lte | No | Only events created at or before this instant. ISO 8601 with an offset, e.g. `2026-09-10T00:00:00Z`. | |
| event_types | No | Filter to several event types at once, e.g. `message.sent` and `message.delivered`. Same vocabulary as `event_type`. The API accepts at most 20. | |
| number_alias | No | Restrict results to one inbox by the alias it had when the event happened, so events from before a rename are missed. Use `number_id` to follow a number across renames. **Absent means every number**, which is the usual choice. Note this is a filter, not a subject: unlike the messaging tools it does not default to `main`. Setting it also excludes `storage.*` and `media.unavailable` events, which belong to the organization rather than to any one number. | |
| ending_before | No | Catch up: return events NEWER than this id. Pass the newest id you have already handled to see only what has happened since. This is the one to poll with. | |
| starting_after | No | Read further back: return events OLDER than this id. This is the one for walking a backlog, and the wrong one for noticing something new. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||