# List calendar events

`GET /calendar.list`

## Description

List events from the authenticated user's connected calendars within
a date range.

Pulls events from every active personal calendar attached to the user
(e.g. Google, Microsoft) and merges them into a single chronological
list. Canceled events are omitted.

**Date range:** Defaults to a 7-day window starting today (caller's
timezone). Pass `startDate` to shift the window's start; pass
`endDate` to set its end (inclusive). Both are interpreted as
`YYYY-MM-DD` in the caller's timezone.

**Access:** Personal access only. Organization tokens do not have
access to individual calendars and receive a `400`.

**Required scope:** `calendar:read`

`meetings:read` also grants this endpoint, but only for API clients
registered **before 2026-07-29T00:00Z**. Clients registered on or after that
date must hold `calendar:read`, or the call fails with `403` /
`missing_scope`. See [Scopes](/docs/guides/scopes).

---

**OpenAPI Spec:** [chat-v1.json](https://developer.ro.am/chat-v1.json)

## Authentication

```
Authorization: Bearer YOUR_API_KEY
```

## Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `startDate` | query | string | No | First day to include (`YYYY-MM-DD`, caller's timezone). Defaults to today. |
| `endDate` | query | string | No | Last day to include (`YYYY-MM-DD`, caller's timezone, inclusive). Defaults to seven days after the resolved `startDate`.  |

## Responses

### 200 - Calendar events retrieved successfully.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `events` | object[] | Yes |  |

**events** (array item):

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `id` | string | Yes | Provider-specific event ID. |
| `title` | string | Yes |  |
| `description` | string | No |  |
| `startTime` | string | Yes | Event start time (RFC3339, caller's timezone). |
| `endTime` | string | Yes | Event end time (RFC3339, caller's timezone). |
| `weekday` | string | Yes | Weekday name (`Monday`, `Tuesday`, …) of `startTime` in the caller's timezone. |
| `allDay` | boolean | No | `true` for all-day events. All-day events are emitted at UTC midnight without timezone conversion.  |
| `location` | string | No | Conference URL if the event has video conferencing attached (preferring video entry points).  |
| `invites` | object[] | Yes |  |
| `organizer` | string | No | Organizer email address. |
| `rrule` | string | No | iCalendar RFC 5545 recurrence rule for the master event in a recurring series. Mutually exclusive with `recurringEventId`.  |
| `recurringEventId` | string | No | Master event ID when this event is one instance of a recurring series.  |
| `meetingLinkId` | string | No | Roam meeting link attached to the event, if any.  |

**invites** (array item):

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `name` | string | No |  |
| `email` | string | No |  |
| `responseStatus` | string | No | RSVP status from the calendar provider. |


#### Example Response

```json
{
  "events": [
    {
      "id": "evt_01HX3YABCDEF",
      "title": "Q2 Planning",
      "description": "Plan Q2 roadmap",
      "startTime": "2026-04-21T10:00:00-07:00",
      "endTime": "2026-04-21T11:00:00-07:00",
      "weekday": "Tuesday",
      "location": "https://ro.am/r/#/d/abc123xyz/def456uvw",
      "invites": [
        {
          "name": "Sam Smith",
          "email": "sam@example.com",
          "responseStatus": "accepted"
        }
      ],
      "organizer": "host@example.com",
      "meetingLinkId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  ]
}
```

### 400 - Bad request. Common causes:
- Organization token (calendar.list is Personal access only)
- Invalid `startDate` or `endDate` format


### 401 - Presented invalid authentication credentials.

### 405 - An unsupported method was requested.

### 500 - An internal error occurred.

---

*Machine-readable API documentation.*
*Full documentation: https://developer.ro.am/docs/api/calendar-list*