---
availability: INSTALLABLE
installation_asset_uuid: 6d18a579-ca86-4bc7-8c71-53a6eb530a29
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%3EOutlook%3C%2Fb%3E+calendar+for+tomorrow%2C+October+24th...%22%2C%22connectorName%22%3A%22outlook%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%22outlook%22%2C%22citationTitle%22%3A%22Engineering+Standup%22%7D%2C%7B%22connectorName%22%3A%22outlook%22%2C%22citationTitle%22%3A%221%3A1+with+Jordan+Smith%22%7D%2C%7B%22connectorName%22%3A%22outlook%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%3EOutlook%3C%2Fb%3E...%22%2C%22connectorName%22%3A%22outlook%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+Microsoft+Teams%3C%2Fli%3E%3C%2Ful%3E%22%7D%2C%7B%22citations%22%3A%5B%7B%22connectorName%22%3A%22outlook%22%2C%22citationTitle%22%3A%22FY25+Budget+Alignment%22%7D%5D%7D%5D%7D%5D%7D
solution_tags:
- Finance - Other
- HR - Other
- IT
- Productivity
- Sales
systems:
- outlook
description: See what's on your calendar for any time range, for yourself or shared calendars.
---
# 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%3EOutlook%3C%2Fb%3E+calendar+for+tomorrow%2C+October+24th...%22%2C%22connectorName%22%3A%22outlook%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%22outlook%22%2C%22citationTitle%22%3A%22Engineering+Standup%22%7D%2C%7B%22connectorName%22%3A%22outlook%22%2C%22citationTitle%22%3A%221%3A1+with+Jordan+Smith%22%7D%2C%7B%22connectorName%22%3A%22outlook%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%3EOutlook%3C%2Fb%3E...%22%2C%22connectorName%22%3A%22outlook%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+Microsoft+Teams%3C%2Fli%3E%3C%2Ful%3E%22%7D%2C%7B%22citations%22%3A%5B%7B%22connectorName%22%3A%22outlook%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. Microsoft Graph Connector
This plugin requires an active **Microsoft Graph connector** configured with the OAuth 2.0 Authorization Code (User Consent Auth) flow.
- If you have not already set up the connector, follow the [**Microsoft Graph Connector Guide**](https://marketplace.moveworks.com/connectors/microsoft-graph#how-to-implement) before proceeding. Please follow the ‘OAuth 2.0 with Authorization Code (User Consent Auth) Setup’ section.
- 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. Microsoft 365 System Requirements
### a. End User Permissions
To search calendar events through this plugin, users must already have access to view calendar data in Microsoft 365 — the same access required to view events in Outlook.
At a minimum, end users must have:
- A licensed Microsoft 365 account with an active Exchange Online mailbox
- Permission to view their own calendar
- If searching a shared calendar — the calendar owner must have explicitly granted the user delegate or shared access in Outlook
### b. Timezone and Working Hours Configuration for End User
For calendar events to display in the correct local time, each user must have their timezone and working hours configured in Outlook. If this is not set, event times will be returned in UTC.
To configure timezone and working hours in Outlook:
1. Open **Outlook** and go to **Settings → View all Outlook settings → Calendar → View**.
2. Under **Time zone**, select your local timezone from the dropdown.
3. Under **Working hours**, set your working days and start/end times.
### c. API Permissions
The Microsoft Graph connector uses **delegated permissions** to retrieve calendar data on behalf of the authenticated user. The following permissions are required for this plugin:
| Permission | Purpose |
| --- | --- |
| `Calendars.ReadWrite` | Read the user's calendar events |
| `Place.Read.All` | Read room and location data associated with events |
| `User.Read` | Read user profiles for looking up attendees and other users |
| `offline_access` | Maintain access via refresh tokens |
**Note:** This plugin does not grant new permissions. It operates within the calendar access already granted to the authenticated user in Microsoft 365.
## Implementation Details
This plugin works by making a sequence of API calls behind the scenes to retrieve the information you need. The diagram below gives you a high-level picture of that flow, followed by a breakdown of each API call — what it does, what it sends, and what it returns. Understanding this will help you configure the plugin correctly and troubleshoot if something doesn't look right.
### Visual Representation of How the Plugin Works
### API Details
This plugin uses two Microsoft Graph API calls.
### API #1: Get User Timezone
Retrieves the authenticated user's timezone as configured in their Outlook mailbox settings. This is used to ensure all event times are returned in the correct local timezone.
```bash
curl --request GET \
--url 'https://graph.microsoft.com/v1.0/me/mailboxSettings' \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Content-Type: application/json'
```
**Key fields returned:**
- `timeZone` *(string)* — The user's configured timezone (e.g., `Pacific Standard Time`). This value is passed as an input to API #2.
### API #2: Get Calendar Events for Time Range
Retrieves all calendar events for a specified user within a given time range. Uses the `calendarView` endpoint which automatically expands recurring event instances within the requested window.
```bash
curl --request GET \
--url 'https://graph.microsoft.com/v1.0/users/{{email}}/calendarView?startDateTime={{start_date_range}}&endDateTime={{end_date_range}}' \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Content-Type: application/json' \
--header 'Prefer: outlook.timezone="{{timezone}}"'
```
**Query Parameters:**
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string | Yes | The UPN (email address) of the user whose calendar is being retrieved. Example: `john.doe@company.com` |
| `startDateTime` | string | Yes | Start of the time range in ISO 8601 format with timezone offset. Example: `2026-01-26T00:00:00-08:00` |
| `endDateTime` | 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 `calendarView` endpoint automatically expands recurring event instances within the requested time range, rather than returning the master recurrence series.
- The `Prefer: outlook.timezone` header localizes returned event times to the user's configured timezone from API #1. If not set, times are returned in UTC.
- We have set the limit for this API to 350. For users with a very high volume of events in the requested range, results may be incomplete.
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 Outlook
- Returns event details including subject, start and end time, location, organizer, attendees, online meeting link, and response status
## 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 Outlook. This plugin mirrors Outlook permissions — if a calendar is shared with the user in Outlook, it will be accessible here.
- Cancelled instances of recurring events may not always be reliably returned — this is a known limitation of the Microsoft Graph `calendarView` endpoint ([reference](https://learn.microsoft.com/en-us/answers/questions/5534938/unable-to-retrieve-cancelled-and-exception-occurre)).
- We’ve set the limit of the search API to return a maximum of 350 events per request — users with a very high volume of events in the requested time range may receive incomplete results.