List events

Namespace: microsoft.graph

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:

  • If the app has application permissions, or,
  • If the app has the appropriate delegated permissions from one user, and another user has shared a calendar with that user, or, has given delegated access to that user. See details and an example.

This API is available in the following national cloud deployments.

Global service US Government L4 US Government L5 (DOD) China operated by 21Vianet

Support various time zones

For all GET operations that return events, you can use the Prefer: outlook.timezone header to specify the time zone for the event start and end times in the response.

For example, the following Prefer: outlook.timezone header sets the start and end times in the response to Eastern Standard Time.

Prefer: outlook.timezone="Eastern Standard Time"

If the event was created in a different time zone, the start and end times will be adjusted to the time zone specified in that Prefer header. See this list for the supported time zone names. If the Prefer: outlook.timezone header is not specified, the start and end times are returned in UTC.

You can use the OriginalStartTimeZone and OriginalEndTimeZone properties on the event resource to find out the time zone used when the event was created.

Permissions

One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

Permission type Permissions (from least to most privileged)
Delegated (work or school account) Calendars.ReadBasic, Calendars.Read, Calendars.ReadWrite
Delegated (personal Microsoft account) Calendars.ReadBasic, Calendars.Read, Calendars.ReadWrite
Application Calendars.ReadBasic, Calendars.Read, Calendars.ReadWrite

HTTP request

GET /me/events
GET /users/{id | userPrincipalName}/events

GET /me/calendar/events
GET /users/{id | userPrincipalName}/calendar/events

GET /me/calendars/{id}/events
GET /users/{id | userPrincipalName}/calendars/{id}/events

GET /me/calendarGroups/{id}/calendars/{id}/events
GET /users/{id | userPrincipalName}/calendarGroups/{id}/calendars/{id}/events

Optional query parameters

This method supports the OData query parameters to help customize the response.

Note

You can't use the $filter parameter to filter on the recurrence property.

Request headers

Name Type Description
Authorization string Bearer {token}. Required. Learn more about authentication and authorization.
Prefer: outlook.timezone string Use this to specify the time zone for start and end times in the response. If not specified, those time values are returned in UTC. Optional.
Prefer: outlook.body-content-type string The format of the body property to be returned in. Values can be "text" or "html". A Preference-Applied header is returned as confirmation if this Prefer header is specified. If the header is not specified, the body property is returned in HTML format. Optional.

Request body

Don't supply a request body for this method.

Response

If successful, this method returns a 200 OK response code and collection of event objects in the response body.

Examples

Request

The following example shows a request. It specifies the following:

  • A Prefer: outlook.timezone header to get date time values returned in Pacific Standard Time.
  • A $select query parameter to return specific properties. Without a $select parameter, all of the event properties will be returned.
GET https://graph.microsoft.com/v1.0/me/events?$select=subject,body,bodyPreview,organizer,attendees,start,end,location
Prefer: outlook.timezone="Pacific Standard Time"

Response

The following example shows the response. The body property is returned in the default HTML format.

HTTP/1.1 200 OK
Content-type: application/json
Preference-Applied: outlook.timezone="Pacific Standard Time"

{
    "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users('cd209b0b-3f83-4c35-82d2-d88a61820480')/events(subject,body,bodyPreview,organizer,attendees,start,end,location)",
    "value":[
        {
            "@odata.etag":"W/\"ZlnW4RIAV06KYYwlrfNZvQAAKGWwbw==\"",
            "id":"AAMkAGIAAAoZDOFAAA=",
            "subject":"Orientation ",
            "bodyPreview":"Dana, this is the time you selected for our orientation. Please bring the notes I sent you.",
            "body":{
                "contentType":"html",
                "content":"<html><head></head><body><p>Dana, this is the time you selected for our orientation. Please bring the notes I sent you.</p></body></html>"
            },
            "start":{
                "dateTime":"2017-04-21T10:00:00.0000000",
                "timeZone":"Pacific Standard Time"
            },
            "end":{
                "dateTime":"2017-04-21T12:00:00.0000000",
                "timeZone":"Pacific Standard Time"
            },
            "location": {
                "displayName": "Assembly Hall",
                "locationType": "default",
                "uniqueId": "Assembly Hall",
                "uniqueIdType": "private"
            },
            "locations": [
                {
                    "displayName": "Assembly Hall",
                    "locationType": "default",
                    "uniqueIdType": "unknown"
                }
            ],
            "attendees":[
                {
                    "type":"required",
                    "status":{
                        "response":"none",
                        "time":"0001-01-01T00:00:00Z"
                    },
                    "emailAddress":{
                        "name":"Samantha Booth",
                        "address":"samanthab@contoso.com"
                    }
                },
                {
                    "type":"required",
                    "status":{
                        "response":"none",
                        "time":"0001-01-01T00:00:00Z"
                    },
                    "emailAddress":{
                        "name":"Dana Swope",
                        "address":"danas@contoso.com"
                    }
                }
            ],
            "organizer":{
                "emailAddress":{
                    "name":"Samantha Booth",
                    "address":"samanthab@contoso.com"
                }
            }
        }
    ]
}