---
availability: INSTALLABLE
installation_asset_uuid: 1c1b66a7-3576-4ef8-9437-d076a9cce5a5
description: See what's on your calendar for any time range, for yourself or shared calendars.
name: Search Calendar Events
purple_chat_link: https://marketplace.moveworks.com/purple-chat?conversation=%7B%22messages%22%3A%5B%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22What%27s+on+my+calendar+for+tomorrow+morning%3F%22%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22reasoningSteps%22%3A%5B%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22Checking+your+%3Cb%3EGoogle+Calendar%3C%2Fb%3E+for+tomorrow%2C+October+24th...%22%2C%22connectorName%22%3A%22google-calendar%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EYou+have+3+events+tomorrow+morning%3A%3C%2Fp%3E%3Cul%3E%3Cli%3E%3Cstrong%3E9%3A00+AM%3C%2Fstrong%3E%3A+Engineering+Standup%3C%2Fli%3E%3Cli%3E%3Cstrong%3E10%3A30+AM%3C%2Fstrong%3E%3A+1%3A1+with+%3Ci%3EJordan+Smith%3C%2Fi%3E%3C%2Fli%3E%3Cli%3E%3Cstrong%3E11%3A30+AM%3C%2Fstrong%3E%3A+Project+Titan+Kickoff%3C%2Fli%3E%3C%2Ful%3E%22%7D%2C%7B%22citations%22%3A%5B%7B%22connectorName%22%3A%22google-calendar%22%2C%22citationTitle%22%3A%22Engineering+Standup%22%7D%2C%7B%22connectorName%22%3A%22google-calendar%22%2C%22citationTitle%22%3A%221%3A1+with+Jordan+Smith%22%7D%2C%7B%22connectorName%22%3A%22google-calendar%22%2C%22citationTitle%22%3A%22Project+Titan+Kickoff%22%7D%5D%7D%5D%7D%2C%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22Find+my+next+meeting+with+Sarah+about+the+budget+review.%22%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22reasoningSteps%22%3A%5B%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22Searching+for+users+named+%5C%22Sarah%5C%22...%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EI+found+a+few+people+named+%5C%22Sarah%5C%22+you+frequently+meet+with.+Which+one+did+you+mean%3F%3C%2Fp%3E%3Cul%3E%3Cli%3ESarah+Jenkins+%28Finance%29%3C%2Fli%3E%3Cli%3ESarah+Miller+%28Product%29%3C%2Fli%3E%3C%2Ful%3E%22%7D%5D%7D%2C%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22Sarah+Jenkins%22%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22reasoningSteps%22%3A%5B%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22Fetching+meeting+details+from+%3Cb%3EGoogle+Calendar%3C%2Fb%3E...%22%2C%22connectorName%22%3A%22google-calendar%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EI%27ve+found+your+next+meeting+with+%3Cstrong%3ESarah+Jenkins%3C%2Fstrong%3E+regarding+the+budget.%3C%2Fp%3E%3Cul%3E%3Cli%3E%3Cstrong%3EMeeting%3A%3C%2Fstrong%3E+FY25+Budget+Alignment%3C%2Fli%3E%3Cli%3E%3Cstrong%3ETime%3A%3C%2Fstrong%3E+Friday%2C+Oct+25+at+2%3A00+PM%3C%2Fli%3E%3Cli%3E%3Cstrong%3ELocation%3A%3C%2Fstrong%3E+Google+Meet%3C%2Fli%3E%3C%2Ful%3E%22%7D%2C%7B%22citations%22%3A%5B%7B%22connectorName%22%3A%22google-calendar%22%2C%22citationTitle%22%3A%22FY25+Budget+Alignment%22%7D%5D%7D%5D%7D%5D%7D
solution_tags:
- Productivity
systems:
- google-calendar
---

# Description

Search and retrieve calendar events so you can quickly check what's ahead, stay on top of your schedule, and make decisions with full context.

# User Experience Preview

Please refer to the following [**Purple Chat**](https://marketplace.moveworks.com/purple-chat?conversation=%7B%22messages%22%3A%5B%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22What%27s+on+my+calendar+for+tomorrow+morning%3F%22%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22reasoningSteps%22%3A%5B%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22Checking+your+%3Cb%3EGoogle+Calendar%3C%2Fb%3E+for+tomorrow%2C+October+24th...%22%2C%22connectorName%22%3A%22google-calendar%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EYou+have+3+events+tomorrow+morning%3A%3C%2Fp%3E%3Cul%3E%3Cli%3E%3Cstrong%3E9%3A00+AM%3C%2Fstrong%3E%3A+Engineering+Standup%3C%2Fli%3E%3Cli%3E%3Cstrong%3E10%3A30+AM%3C%2Fstrong%3E%3A+1%3A1+with+%3Ci%3EJordan+Smith%3C%2Fi%3E%3C%2Fli%3E%3Cli%3E%3Cstrong%3E11%3A30+AM%3C%2Fstrong%3E%3A+Project+Titan+Kickoff%3C%2Fli%3E%3C%2Ful%3E%22%7D%2C%7B%22citations%22%3A%5B%7B%22connectorName%22%3A%22google-calendar%22%2C%22citationTitle%22%3A%22Engineering+Standup%22%7D%2C%7B%22connectorName%22%3A%22google-calendar%22%2C%22citationTitle%22%3A%221%3A1+with+Jordan+Smith%22%7D%2C%7B%22connectorName%22%3A%22google-calendar%22%2C%22citationTitle%22%3A%22Project+Titan+Kickoff%22%7D%5D%7D%5D%7D%2C%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22Find+my+next+meeting+with+Sarah+about+the+budget+review.%22%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22reasoningSteps%22%3A%5B%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22Searching+for+users+named+%5C%22Sarah%5C%22...%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EI+found+a+few+people+named+%5C%22Sarah%5C%22+you+frequently+meet+with.+Which+one+did+you+mean%3F%3C%2Fp%3E%3Cul%3E%3Cli%3ESarah+Jenkins+%28Finance%29%3C%2Fli%3E%3Cli%3ESarah+Miller+%28Product%29%3C%2Fli%3E%3C%2Ful%3E%22%7D%5D%7D%2C%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22Sarah+Jenkins%22%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22reasoningSteps%22%3A%5B%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22Fetching+meeting+details+from+%3Cb%3EGoogle+Calendar%3C%2Fb%3E...%22%2C%22connectorName%22%3A%22google-calendar%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EI%27ve+found+your+next+meeting+with+%3Cstrong%3ESarah+Jenkins%3C%2Fstrong%3E+regarding+the+budget.%3C%2Fp%3E%3Cul%3E%3Cli%3E%3Cstrong%3EMeeting%3A%3C%2Fstrong%3E+FY25+Budget+Alignment%3C%2Fli%3E%3Cli%3E%3Cstrong%3ETime%3A%3C%2Fstrong%3E+Friday%2C+Oct+25+at+2%3A00+PM%3C%2Fli%3E%3Cli%3E%3Cstrong%3ELocation%3A%3C%2Fstrong%3E+Google+Meet%3C%2Fli%3E%3C%2Ful%3E%22%7D%2C%7B%22citations%22%3A%5B%7B%22connectorName%22%3A%22google-calendar%22%2C%22citationTitle%22%3A%22FY25+Budget+Alignment%22%7D%5D%7D%5D%7D%5D%7D) for a sample conversational experience between a user and the AI Assistant for this plugin.

## Prerequisites

Before installing and using the **Search Calendar Events** plugin, ensure the following requirements are met.

### 1. Google Calendar Connector

This plugin requires an active **Google Calendar connector** configured with the OAuth 2.0 Authorization Code (User Consent Auth) flow.

- If you have not already set up the connector, follow the [**Google Calendar Connector Guide**](https://marketplace.moveworks.com/connectors/google-calendar) before proceeding.
- The connector must be fully configured and tested before installing this plugin.

### 2. Plugin Installation

Once the connector is ready, follow the [**plugin installation documentation**](https://help.moveworks.com/docs/ai-agent-marketplace-installation) for steps on how to install and activate the plugin in Agent Studio.

### 3. Google Workspace System Requirements

### a. End User Permissions

To search calendar events through this plugin, users must already have access to view calendar data in Google Workspace — the same access required to view events in Google Calendar.

At a minimum, end users must have:

- A licensed Google Workspace account with Google Calendar enabled
- Permission to view their own calendar

Note: Event times are automatically displayed in the user's timezone as configured in their Google account. No manual setup is required.

**Looking up another user's calendar:**

A user can only retrieve another user's calendar events if one of the following is true:

- The other user has **explicitly shared their calendar** with the authenticated user in Google Calendar, with at least a `reader` role (full event details) or `freeBusyReader` role (free/busy only, no event details)
- Your **Google Workspace admin has configured org-wide internal calendar sharing**, which sets a default sharing policy across all calendars in the domain — this is the most common reason users can look up colleagues' calendars without explicit sharing

**Note:** The level of event detail returned depends on the access role granted. A `freeBusyReader` role will only return free/busy status, not event titles or details. Check with your Google Workspace admin to confirm your organization's sharing policy.

### b. API Permissions

The Google Calendar connector uses **delegated permissions** to retrieve calendar data on behalf of the authenticated user. The following permission is required for this plugin:

| Permission | Purpose |
| --- | --- |
| `https://www.googleapis.com/auth/calendar` | Read and retrieve the user's calendar events |

## Implementation Details

This plugin works by making a single API call to retrieve calendar events for a user within a specified time range.

### Visual Representation of How the Plugin Works

![image.png](Search%20Calendar%20Events/image.png)

### API Details

This plugin uses one Google Calendar API call.

### API: Get Calendar Events for Time Range

Retrieves all calendar events for a specified user within a given time range. Uses the `events` endpoint which returns event instances including recurring events within the requested window.

```bash
curl --request GET \
  --url 'https://www.googleapis.com/calendar/v3/calendars/{{email}}/events?timeMin={{start_date_range}}&timeMax={{end_date_range}}&singleEvents=true&orderBy=startTime&maxResults=350' \
  --header 'Authorization: Bearer {{access_token}}' \
  --header 'Content-Type: application/json'
```

**Input Arguments:**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string | Yes | The email address of the user whose calendar is being retrieved. Use `primary` to retrieve the authenticated user's own calendar. Example: `john.doe@company.com` |
| `start_date_range` | string | Yes | Start of the time range in ISO 8601 format with timezone offset. Example: `2026-01-26T00:00:00-08:00` |
| `end_date_range` | string | Yes | End of the time range in ISO 8601 format with timezone offset. Example: `2026-01-31T00:00:00-08:00` |

**Key nuances:**

- The plugin retrieves up to **350 events** per request. For users with a very high volume of events in the requested range, results may be incomplete.
- Event times are returned in the timezone specified in the event itself. The AI Assistant will display times in the user's local timezone.

Now that you understand how the plugin works under the hood, let's walk through what it can and can't do. We recommend reading both sections before going live to ensure the best experience for your users.

## What Is In Scope for This Plugin?

This plugin supports the following capabilities:

- Retrieve calendar events for the **authenticated user** within a specified time range
- Retrieve calendar events from **calendars shared with the authenticated user**, provided access has been granted in Google Calendar
- Returns event details including subject, start and end time, location, organizer, attendees, video call link, and response status
- Supports retrieval of `default`, `focusTime`, and `outOfOffice` event types

## What Is Out of Scope for This Plugin?

This plugin does **not** support the following:

- Finding availability or suggesting meeting times — handled by a separate **Find Availability** plugin
- Accessing calendars that have not been shared with the authenticated user in Google Calendar
- Users with a very high volume of events in the requested time range may receive incomplete results, as the API is limited to returning a maximum of **350 events** per request