List events with the Google Calendar API
Lists the events of a calendar. Set singleEvents to true to expand recurring events, which is required to order by startTime.
- Identifier
- google_calendar_list_events
The request
POST https://connect.reportei.com/api/tools/google_calendar_list_events/execute
Authorization: Bearer <merchant token>
x-customer-token: <customer token>
Content-Type: application/json
Accept: application/json
{
"customer_toolkit": "<connection UUID>",
"arguments": {
"calendarId": "<calendarId>"
}
}Your system sends your customer's connection id and the tool arguments. The headers are the same as the rest of the Connect API: your product's token and your customer's token.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| calendarId | string | Yes | Calendar id from List calendars, or primary. |
| timeMin | string | No | Exclusive lower bound for the event end time, RFC3339 with offset. |
| timeMax | string | No | Exclusive upper bound for the event start time, RFC3339 with offset. |
| q | string | No | Free text searched in summary, description, location and attendees. |
| singleEvents | boolean | No | Expands recurring events into single instances. |
| orderBy | string | No | startTime requires singleEvents set to true.Values: startTime, updated |
| maxResults | integer | No | Results per page. The default is 250. |
| pageToken | string | No | The nextPageToken of the previous response. |
Supported connections
Your customer connects their Google Calendar account once, with one of the modes below. The same connection serves every tool of the toolkit.
OAuth with your product's app
You register your product's OAuth app once, with POST /api/merchants/credentials/google_calendar, and your customer authorizes the account on a consent screen. Connect renews the token when it is about to expire.
The response
On success, Connect preserves the app's response status and body. HTTP errors returned by the app use the {error, api_error} envelope; authentication or validation can fail before execution. The X-Toolkit-Execution-Id header identifies the recorded execution, available at GET /api/tools/executions/{uuid}.
Ready for AI agents
This tool's input is a JSON Schema, available at GET /api/tools/google_calendar_list_events. It becomes your agent's tool definition with no conversion.
Other Google Calendar tools
- List calendarsGETLists the calendars on the user's calendar list. Use the id of an item as calendarId in the event tools. The id primary is the user's main calendar.
- Create eventPOSTCreates an event. Use start.dateTime and end.dateTime for a timed event, or start.date and end.date for an all-day event. sendUpdates decides who is emailed about it. A Google Meet link needs conferenceData with conferenceDataVersion 1.
- Get eventGETReturns one event with its attendees and their responses, the Meet link in hangoutLink, and recurringEventId when it is an instance of a recurring event.
- Update eventPATCHChanges the fields sent and keeps the others. A list, such as attendees or recurrence, replaces the whole list, so send every attendee that should stay. sendUpdates decides who is emailed about the change.
- Delete eventDELETEDeletes an event. The id of a recurring event deletes the whole series; the id of one instance deletes only that one. sendUpdates decides who is emailed about the cancellation. The response is empty, status 204.
- Get free/busyPOSTReturns the busy intervals of one or more calendars between timeMin and timeMax, under calendars, keyed by calendar id. A calendar the user cannot see comes back with errors instead of busy.
- Create calendarPOSTCreates a secondary calendar owned by the user, such as a content calendar for one client. The id in the response goes in calendarId of the event tools.
Toolkits in the same category
See all 100 toolkitsSee Connect applied to your product.
Try it for 15 days with no card, or walk our team through your use case.
