List calendar events | Athena | API Reference Docs

List events on the calendar of the caller’s connected account.

Reads the primary Google Calendar of a Gmail account or the default calendar of an Outlook account. start/end select the events overlapping that window; without them, Outlook returns recurring series as single entries, so supply a window to expand them. title, location and attendees filter the events that were read.

List events on the calendar of the caller's connected account. Reads the primary Google Calendar of a Gmail account or the default calendar of an Outlook account. `start`/`end` select the events overlapping that window; without them, Outlook returns recurring series as single entries, so supply a window to expand them. `title`, `location` and `attendees` filter the events that were read.

Authentication

X-API-KEYstring

API Key authentication via header

Query parameters

titlestring or nullOptional

Text filter. On Outlook this matches the event title only (contains(subject, …)); on Google Calendar it is Google’s free-text event search (q), which also matches the description, location and attendee names.

startstring or nullOptional

Window start. start and end select events that overlap the window: an event that begins before start but is still running at start is included. ISO 8601 with an explicit UTC offset or Z (e.g. 2026-10-01T00:00:00-04:00); the instant is forwarded in RFC 3339 form. Recurring series are expanded into their instances inside the window. Given only one bound, Google leaves the other side open while Outlook derives it 60 days away.

Window start. `start` and `end` select events that overlap the window: an event that begins before `start` but is still running at `start` is included. ISO 8601 with an explicit UTC offset or Z (e.g. `2026-10-01T00:00:00-04:00`); the instant is forwarded in RFC 3339 form. Recurring series are expanded into their instances inside the window. Given only one bound, Google leaves the other side open while Outlook derives it 60 days away.

endstring or nullOptional

Window end (see start); must be later than start when both are given. ISO 8601 with an explicit UTC offset or Z.

locationstring or nullOptional

Only events whose location contains this text. Applied after up to limit events have been read from the provider, so narrow the window with start/end when looking for a specific event.

attendeesstring or nullOptional

Only events with at least one of these attendee emails (comma-separated). Applied after up to limit events have been read from the provider, so narrow the window with start/end when looking for a specific event.

limitintegerOptional1-200Defaults to 50

Maximum number of events (1-200).

catalog_idstring or nullOptional

Connected email account to use, as the catalog asset id returned by the Athena UI or the assets API. Defaults to the caller's default email account. An id that is not one of the caller's own connected accounts in the current workspace is a 404.

Response

Successful Response

catalog_idstring

The connected account that was read.

countinteger

Number of events returned.

providerstring

Account provider as Athena reports it: gmail or outlook for accounts connected through the Integrations page; google or microsoft365 for directly-connected accounts (read-only for drafts).

resultslist of objectsOptional

Matching events in ascending start order.

Errors

400

Bad Request Error

403

Forbidden Error

404

Not Found Error

422

Unprocessable Entity Error

429

Too Many Requests Error

502

Bad Gateway Error