# google-calendar.events.list

Events on a calendar between two times or matching a search

> Returns events on the specified calendar.

Page: https://telipot.com/catalog/tasks/google-calendar.events.list · Markdown: https://telipot.com/catalog/tasks/google-calendar.events.list/md · JSON: https://telipot.com/catalog/tasks/google-calendar.events.list/json

| Field | Value |
| --- | --- |
| provider | [Google Calendar](https://telipot.com/catalog/providers/google-calendar) `google-calendar` |
| capability | [`calendar.events.list`](https://telipot.com/catalog/capabilities/calendar.events.list) |
| kind | data |
| tier | core |
| price | Free (Free from the tool) |
| identity | Person’s own |
| auth | `oauth · OAuth 2.0 with PKCE` |
| scope | own_account |
| principal | user |
| required_scopes | `calendar.readonly` |
| retention | standard |
| route | `GET https://www.googleapis.com/calendar/v3/calendars/{calendarId}/events` |
| verification | Not verified yet. Not checked yet. We test with a real request before we mark it. |
| status | live |
| docs | https://developers.google.com/workspace/calendar/api/v3/reference/events/list |

## Preview the price · nothing runs

```bash
telipot run google-calendar.events.list \
  --input-json '{"calendarId":"primary"}' \
  --as user:ana \
  --quote
```

## Run it

```bash
telipot run google-calendar.events.list \
  --input-json '{"calendarId":"primary"}' \
  --as user:ana
```

```bash
curl https://api.telipot.com/v1/tasks/google-calendar.events.list/run \
  -H "Authorization: Bearer $TELIPOT_TOKEN" \
  -H "Telipot-Principal: user:ana" \
  -H "Content-Type: application/json" \
  -d '{"calendarId":"primary"}'
```

## Input

| Field | In | Type | Required | Constraints | Note |
| --- | --- | --- | --- | --- | --- |
| `calendarId` | pathParams | string | yes |  | primary for the connected account's own calendar, or an id from google-calendar.calendars.list |
| `timeMin` | queryParams | string | no |  | Keep events that end after this RFC 3339 time, which needs an offset |
| `timeMax` | queryParams | string | no |  | Keep events that start before this RFC 3339 time, which needs an offset |
| `q` | queryParams | string | no |  | Free text matched against the title, description, location and the attendees' and organizer's names and addresses |
| `singleEvents` | queryParams | boolean | no | default false | true expands a recurring event into its instances and leaves out the recurring event itself |
| `orderBy` | queryParams | string | no | one of "startTime", "updated" | startTime needs singleEvents true; an unspecified, stable order when absent |
| `maxResults` | queryParams | integer | no | 1 to 2500; default 250 | Events on one page, which may hold fewer even when more match; a nextPageToken says there are more |
| `pageToken` | queryParams | string | no |  | The nextPageToken of the previous page |
| `showDeleted` | queryParams | boolean | no | default false | Whether to include cancelled events |
| `updatedMin` | queryParams | string | no |  | Keep events changed after this RFC 3339 time, deleted ones included |
| `timeZone` | queryParams | string | no |  | The time zone of the times in the answer; the calendar's own when absent |

## Input schema

```json
{
  "type": "object",
  "properties": {
    "calendarId": {
      "type": "string",
      "description": "primary for the connected account's own calendar, or an id from google-calendar.calendars.list",
      "examples": [
        "primary"
      ]
    },
    "timeMin": {
      "type": "string",
      "description": "Keep events that end after this RFC 3339 time, which needs an offset",
      "examples": [
        "2026-10-12T00:00:00Z"
      ]
    },
    "timeMax": {
      "type": "string",
      "description": "Keep events that start before this RFC 3339 time, which needs an offset",
      "examples": [
        "2026-10-19T00:00:00Z"
      ]
    },
    "q": {
      "type": "string",
      "description": "Free text matched against the title, description, location and the attendees' and organizer's names and addresses",
      "examples": [
        "planning"
      ]
    },
    "singleEvents": {
      "type": "boolean",
      "description": "true expands a recurring event into its instances and leaves out the recurring event itself",
      "default": false
    },
    "orderBy": {
      "type": "string",
      "description": "startTime needs singleEvents true; an unspecified, stable order when absent",
      "enum": [
        "startTime",
        "updated"
      ]
    },
    "maxResults": {
      "type": "integer",
      "description": "Events on one page, which may hold fewer even when more match; a nextPageToken says there are more",
      "default": 250,
      "minimum": 1,
      "maximum": 2500
    },
    "pageToken": {
      "type": "string",
      "description": "The nextPageToken of the previous page"
    },
    "showDeleted": {
      "type": "boolean",
      "description": "Whether to include cancelled events",
      "default": false
    },
    "updatedMin": {
      "type": "string",
      "description": "Keep events changed after this RFC 3339 time, deleted ones included"
    },
    "timeZone": {
      "type": "string",
      "description": "The time zone of the times in the answer; the calendar's own when absent",
      "examples": [
        "America/Los_Angeles"
      ]
    }
  },
  "required": [
    "calendarId"
  ],
  "additionalProperties": false
}
```

## Output schema

```json
{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "description": "Cancelled events appear only with showDeleted or updatedMin",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "description": "confirmed, tentative or cancelled"
          },
          "summary": {
            "type": "string",
            "description": "The title"
          },
          "description": {
            "type": "string",
            "description": "The description; it can hold HTML"
          },
          "location": {
            "type": "string"
          },
          "htmlLink": {
            "type": "string",
            "description": "A link to the event in the Google Calendar web app"
          },
          "created": {
            "type": "string",
            "description": "RFC 3339 time"
          },
          "updated": {
            "type": "string",
            "description": "RFC 3339 time of the last change to the main event data"
          },
          "creator": {
            "type": "object",
            "properties": {
              "email": {
                "type": "string"
              },
              "displayName": {
                "type": "string"
              },
              "self": {
                "type": "boolean"
              }
            }
          },
          "organizer": {
            "type": "object",
            "properties": {
              "email": {
                "type": "string"
              },
              "displayName": {
                "type": "string"
              },
              "self": {
                "type": "boolean"
              }
            }
          },
          "start": {
            "type": "object",
            "description": "A date for an all-day event, or a dateTime with its offset",
            "properties": {
              "date": {
                "type": "string"
              },
              "dateTime": {
                "type": "string"
              },
              "timeZone": {
                "type": "string"
              }
            }
          },
          "end": {
            "type": "object",
            "description": "Exclusive; a date for an all-day event, or a dateTime with its offset",
            "properties": {
              "date": {
                "type": "string"
              },
              "dateTime": {
                "type": "string"
              },
              "timeZone": {
                "type": "string"
              }
            }
          },
          "recurrence": {
            "type": "array",
            "description": "RRULE, EXRULE, RDATE and EXDATE lines of a recurring event",
            "items": {
              "type": "string"
            }
          },
          "recurringEventId": {
            "type": "string",
            "description": "The id of the recurring event this is an instance of"
          },
          "originalStartTime": {
            "type": "object",
            "properties": {
              "date": {
                "type": "string"
              },
              "dateTime": {
                "type": "string"
              },
              "timeZone": {
                "type": "string"
              }
            }
          },
          "attendees": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "email": {
                  "type": "string"
                },
                "displayName": {
                  "type": "string"
                },
                "responseStatus": {
                  "type": "string",
                  "description": "needsAction, declined, tentative or accepted"
                },
                "organizer": {
                  "type": "boolean"
                },
                "self": {
                  "type": "boolean"
                },
                "resource": {
                  "type": "boolean"
                },
                "optional": {
                  "type": "boolean"
                }
              }
            }
          },
          "attendeesOmitted": {
            "type": "boolean"
          },
          "hangoutLink": {
            "type": "string"
          },
          "conferenceData": {
            "type": "object",
            "description": "The conference details such as a Google Meet link"
          },
          "visibility": {
            "type": "string",
            "description": "default, public, private or confidential"
          },
          "transparency": {
            "type": "string",
            "description": "opaque when the event blocks time, transparent when it does not"
          },
          "eventType": {
            "type": "string",
            "description": "default, birthday, focusTime, fromGmail, outOfOffice or workingLocation"
          },
          "colorId": {
            "type": "string"
          },
          "iCalUID": {
            "type": "string"
          },
          "sequence": {
            "type": "integer"
          },
          "reminders": {
            "type": "object",
            "properties": {
              "useDefault": {
                "type": "boolean"
              },
              "overrides": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "method": {
                      "type": "string"
                    },
                    "minutes": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "etag": {
            "type": "string"
          },
          "kind": {
            "type": "string"
          }
        }
      }
    },
    "summary": {
      "type": "string",
      "description": "The title of the calendar"
    },
    "description": {
      "type": "string"
    },
    "timeZone": {
      "type": "string"
    },
    "accessRole": {
      "type": "string",
      "description": "none, freeBusyReader, reader, writer or owner"
    },
    "updated": {
      "type": "string",
      "description": "RFC 3339 time of the last change to the calendar"
    },
    "defaultReminders": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "method": {
            "type": "string"
          },
          "minutes": {
            "type": "integer"
          }
        }
      }
    },
    "nextPageToken": {
      "type": "string",
      "description": "Absent on the last page"
    },
    "nextSyncToken": {
      "type": "string"
    },
    "etag": {
      "type": "string"
    },
    "kind": {
      "type": "string"
    }
  }
}
```

## Example response

From `examples/google-calendar.events.list.json`.

```json
{
  "kind": "calendar#events",
  "etag": "\"EXAMPLEETAG\"",
  "summary": "contact@example.com",
  "updated": "2026-10-05T09:12:44.321Z",
  "timeZone": "America/Los_Angeles",
  "accessRole": "owner",
  "defaultReminders": [
    {
      "method": "popup",
      "minutes": 10
    }
  ],
  "items": [
    {
      "kind": "calendar#event",
      "etag": "\"EXAMPLEETAG\"",
      "id": "3vq8k2nd5ho1c7a9f0b4lmetoe",
      "status": "confirmed",
      "htmlLink": "https://www.google.com/calendar/event?eid=EXAMPLE",
      "created": "2026-09-28T16:02:10.000Z",
      "updated": "2026-09-28T16:02:10.512Z",
      "summary": "Planning",
      "creator": {
        "email": "contact@example.com",
        "self": true
      },
      "organizer": {
        "email": "contact@example.com",
        "self": true
      },
      "start": {
        "dateTime": "2026-10-12T10:00:00-07:00",
        "timeZone": "America/Los_Angeles"
      },
      "end": {
        "dateTime": "2026-10-12T10:30:00-07:00",
        "timeZone": "America/Los_Angeles"
      },
      "sequence": 0,
      "attendees": [
        {
          "email": "contact@example.com",
          "organizer": true,
          "self": true,
          "responseStatus": "accepted"
        },
        {
          "email": "guest@example.com",
          "responseStatus": "needsAction"
        }
      ],
      "reminders": {
        "useDefault": true
      },
      "eventType": "default"
    },
    {
      "kind": "calendar#event",
      "etag": "\"EXAMPLEETAG\"",
      "id": "7h2m9p4k1d8s5q0r3t6vbnmle_20261014T220000Z",
      "status": "confirmed",
      "htmlLink": "https://www.google.com/calendar/event?eid=EXAMPLE",
      "created": "2026-09-01T08:00:00.000Z",
      "updated": "2026-09-01T08:00:00.000Z",
      "summary": "Weekly review",
      "creator": {
        "email": "contact@example.com",
        "self": true
      },
      "organizer": {
        "email": "contact@example.com",
        "self": true
      },
      "start": {
        "dateTime": "2026-10-14T15:00:00-07:00",
        "timeZone": "America/Los_Angeles"
      },
      "end": {
        "dateTime": "2026-10-14T16:00:00-07:00",
        "timeZone": "America/Los_Angeles"
      },
      "recurringEventId": "7h2m9p4k1d8s5q0r3t6vbnmle",
      "originalStartTime": {
        "dateTime": "2026-10-14T15:00:00-07:00",
        "timeZone": "America/Los_Angeles"
      },
      "sequence": 0,
      "reminders": {
        "useDefault": true
      },
      "eventType": "default"
    }
  ]
}
```