list-calendar-events
Read-only
Retrieve calendar events from a user's mailbox with pagination and filtering. Does not expand recurring events; use get-calendar-view for individual instances.
Instructions
Get a list of event objects in the user's mailbox. The list contains single instance meetings and series masters. To get expanded event instances, you can get the calendar view, or get the instances of an event. Currently, this operation returns event bodies in only HTML format. There are two scenarios where an app can get events in another user's calendar:
💡 TIP: WARNING: Does NOT expand recurring events — only returns seriesMaster. Use get-calendar-view instead to see individual occurrences within a date range.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | Page size (Graph $top). Start small (e.g. 5–15) so responses fit the model context; raise only if needed. Use $select to return fewer fields per item. For more rows, use @odata.nextLink from the response instead of a very large $top. | |
| skip | No | Items to skip for pagination. Not supported with $search. | |
| count | No | Set true to enable advanced query mode (ConsistencyLevel: eventual). Required for complex $filter on flag/flagStatus or contains(). | |
| expand | No | Expand related entities | |
| filter | No | OData filter expression. Add $count=true for advanced filters (flag/flagStatus, contains()). Cannot combine with $search. | |
| search | No | KQL search query — wrap value in double quotes. Cannot combine with $filter. | |
| select | No | Comma-separated fields to return, e.g. id,subject,from,receivedDateTime | |
| orderby | No | Sort expression, e.g. receivedDateTime desc | |
| timezone | No | IANA timezone name (e.g., "America/New_York", "Europe/London", "Asia/Tokyo") for calendar event times. If not specified, times are returned in UTC. | |
| fetchAllPages | No | Follow @odata.nextLink and merge up to 100 pages into one response. Can return enormous payloads—only when the user explicitly needs a full export. Prefer a small $top first, then paginate or narrow with $filter/$search. | |
| includeHeaders | No | Include response headers (including ETag) in the response metadata | |
| excludeResponse | No | Exclude the full response body and only return success or failure indication | |
| expandExtendedProperties | No | When true, expands singleValueExtendedProperties on each event. Use this to retrieve custom extended properties (e.g., sync metadata) stored on calendar events. |