listEvents

The window's end is exclusive, and a recurring series comes back as its occurrences, each with its own id, unless you set expandRecurring: false. Use iterateEvents when you want every page without handling cursors.

import { listEvents } from '@cal-sdk/core';

const { events, nextPageToken } = await listEvents({
  calendar,
  timeMin: new Date(),
  timeMax: '2026-12-31T00:00:00Z',
});

OptionsCopy Anchor Link

timeMinDate | string

Start of the window, inclusive. Events that end after it are returned.

timeMaxDate | string

End of the window, exclusive. Events that start before it are returned.

calendarId?string= 'primary'

expandRecurring?boolean= true

true returns occurrences and exceptions, sorted by start. false returns series instead.

query?string

Free-text search. Throws UnsupportedFunctionalityError unless capabilities.events.search is supported.

pageSize?number

Upper bound on events per page. Providers may return fewer.

pageToken?string

nextPageToken from the previous page.

Plus the common options. Strings in timeMin and timeMax are parsed as ISO 8601; one without a time is midnight UTC.

ResultCopy Anchor Link

eventsCalendarEvent[]

nextPageToken?string

Pass as pageToken for the next page. Missing on the last page.

warningsWarning[]

ThrowsCopy Anchor Link

• InvalidArgumentError when timeMax is not after timeMin, or pageSize is not a positive whole number.
• UnsupportedFunctionalityError for query on a provider without search.
• NotFoundError when the calendar does not exist.

iterateEventsCopy Anchor Link

import { iterateEvents } from '@cal-sdk/core';

for await (const event of iterateEvents({ calendar, timeMin, timeMax })) {
  console.log(event.title);
}

Takes the same options as listEvents except pageToken, and yields every event, fetching the next page only when the loop needs it. Warnings go to the warnings setting, since there is no result to return them on.