> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mavioapp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List calendar events

> Retrieve upcoming and past calendar events with their recording status.

Returns a list of calendar events from connected calendars, including whether each event has been or will be recorded by Mavio.

<ParamField query="from" type="string">
  Return events starting on or after this date. ISO 8601 format. Defaults to the start of today.
</ParamField>

<ParamField query="to" type="string">
  Return events starting on or before this date. ISO 8601 format. Defaults to 7 days from now.
</ParamField>

<ParamField query="provider" type="string">
  Filter by calendar provider. One of `google` or `outlook`.
</ParamField>

<ParamField query="recording_status" type="string">
  Filter by recording status. One of `scheduled`, `recording`, `completed`, `skipped`.
</ParamField>

<ParamField query="limit" type="integer" default="20">
  Number of events to return. Between 1 and 100.
</ParamField>

<ParamField query="offset" type="integer" default="0">
  Number of events to skip for pagination.
</ParamField>

### Response

<ResponseField name="data" type="array">
  An array of calendar event objects.

  <Expandable title="Calendar event object">
    <ResponseField name="id" type="string">
      Calendar event identifier.
    </ResponseField>

    <ResponseField name="title" type="string">
      Event title from the calendar.
    </ResponseField>

    <ResponseField name="start_time" type="string">
      ISO 8601 start time.
    </ResponseField>

    <ResponseField name="end_time" type="string">
      ISO 8601 end time.
    </ResponseField>

    <ResponseField name="provider" type="string">
      Calendar provider: `google` or `outlook`.
    </ResponseField>

    <ResponseField name="meeting_platform" type="string | null">
      Detected meeting platform from the event link: `zoom`, `google_meet`, `microsoft_teams`, or `null`.
    </ResponseField>

    <ResponseField name="meeting_url" type="string | null">
      The meeting join URL extracted from the calendar event.
    </ResponseField>

    <ResponseField name="recording_status" type="string">
      One of `scheduled` (bot will join), `recording` (in progress), `completed` (recorded), `skipped` (not recorded).
    </ResponseField>

    <ResponseField name="meeting_id" type="string | null">
      The Mavio meeting ID if a recording exists. `null` if not yet recorded.
    </ResponseField>

    <ResponseField name="attendees" type="array">
      List of attendee emails.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -G https://api.mavioapp.com/v1/calendar/events \
    -H "Authorization: Bearer mvo_live_abc123" \
    -d from=2026-04-14T00:00:00Z \
    -d to=2026-04-21T00:00:00Z \
    -d recording_status=scheduled
  ```

  ```python Python theme={null}
  events = client.calendar.list_events(
      from_date="2026-04-14T00:00:00Z",
      to_date="2026-04-21T00:00:00Z",
      recording_status="scheduled"
  )
  ```

  ```javascript Node.js theme={null}
  const { data } = await client.calendar.listEvents({
    from: '2026-04-14T00:00:00Z',
    to: '2026-04-21T00:00:00Z',
    recording_status: 'scheduled',
  });
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": [
      {
        "id": "evt_g1c2a3l4",
        "title": "Weekly Product Sync",
        "start_time": "2026-04-15T14:00:00Z",
        "end_time": "2026-04-15T14:45:00Z",
        "provider": "google",
        "meeting_platform": "google_meet",
        "meeting_url": "https://meet.google.com/abc-defg-hij",
        "recording_status": "scheduled",
        "meeting_id": null,
        "attendees": ["alice@example.com", "bob@example.com", "carol@example.com"]
      }
    ],
    "pagination": {
      "total": 12,
      "limit": 20,
      "offset": 0,
      "has_more": false
    }
  }
  ```
</ResponseExample>