Get event
Namespace: microsoft.graph
Important
APIs under the /beta
version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported. To determine whether an API is available in v1.0, use the Version selector.
Get the properties and relationships of the specified event object.
An app can get an event in another user's calendar if:
- The app has application permissions
- 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.
Because the event resource supports extensions, you can also use the GET
operation to get custom properties and extension data in an event instance.
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
Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions only if your app requires it. For details about delegated and application permissions, see Permission types. To learn more about these permissions, see the permissions reference.
Permission type | Least privileged permissions | Higher privileged permissions |
---|---|---|
Delegated (work or school account) | Calendars.ReadBasic | Calendars.Read |
Delegated (personal Microsoft account) | Calendars.ReadBasic | Calendars.Read |
Application | Calendars.ReadBasic | Calendars.Read |
HTTP request
GET /me/events/{id}
GET /users/{id | userPrincipalName}/events/{id}
GET /groups/{id}/events/{id}
GET /me/calendar/events/{id}
GET /users/{id | userPrincipalName}/calendar/events/{id}
GET /groups/{id}/calendar/events/{id}
GET /me/calendars/{id}/events/{id}
GET /users/{id | userPrincipalName}/calendars/{id}/events/{id}
GET /me/calendarGroups/{id}/calendars/{id}/events/{id}
GET /users/{id | userPrincipalName}/calendarGroups/{id}/calendars/{id}/events/{id}
Optional query parameters
This method supports the OData query parameters to help customize the response.
Request headers
Name | Type | Description |
---|---|---|
Authorization | string | Bearer {token}. Required. |
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 isn't 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 an event object in the response body.
Examples
Example 1: Get a specified event
Request
The following example gets the specified event. 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.
The request does not specify any Prefer: outlook.body-content-type
header to indicate a specific format for the returned event body.
GET https://graph.microsoft.com/beta/me/events/AAMkAGIAAAoZDOFAAA=?$select=subject,body,bodyPreview,organizer,attendees,start,end,location,hideAttendees
Prefer: outlook.timezone="Pacific Standard Time"
Response
The following example shows the response. Because no Prefer: outlook.body-content-type
header was specified, 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/beta/$metadata#users('cd209b0b-3f83-4c35-82d2-d88a61820480')/events(subject,body,bodyPreview,organizer,attendees,start,end,location,hideAttendees)/$entity",
"@odata.etag":"W/\"ZlnW4RIAV06KYYwlrfNZvQAAKGWwbw==\"",
"id":"AAMkAGIAAAoZDOFAAA=",
"iCalUId": "040000008200E00074=",
"uid": "040000008200E00074C=",
"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":"tentativelyAccepted",
"time":"0001-01-01T00:00:00Z"
},
"proposedNewTime": {
"start": {
"dateTime": "2019-08-16T12:00:00.0000000",
"timeZone": "Pacific Standard Time"
},
"end": {
"dateTime": "2019-08-16T14:00:00.0000000",
"timeZone": "Pacific Standard Time"
}
},
"emailAddress":{
"name":"Dana Swope",
"address":"danas@contoso.com"
}
}
],
"hideAttendees": false,
"organizer":{
"emailAddress":{
"name":"Samantha Booth",
"address":"samanthab@contoso.com"
}
}
}
Example 2: Get the body property in text format
Request
The following example shows how to use a Prefer: outlook.body-content-type="text"
header to get the body property of the specified event in text format.
The request also uses 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/beta/me/events/AAMkAGI1AAAoZDOFAAA=?$select=subject,body,bodyPreview
Prefer: outlook.body-content-type="text"
Response
The following example shows the response. The body property is returned in text format.
HTTP/1.1 200 OK
Content-type: application/json
Preference-Applied: outlook.body-content-type="text"
{
"@odata.context":"https://graph.microsoft.com/beta/$metadata#users('cd209b0b-3f83-4c35-82d2-d88a61820480')/events(subject,body,bodyPreview)/$entity",
"@odata.etag":"W/\"ZlnW4RIAV06KYYwlrfNZvQAAKGWwbw==\"",
"id":"AAMkAGI1AAAoZDOFAAA=",
"iCalUId": "040000008200E00074=",
"uid": "040000008200E00074C=",
"subject":"Orientation ",
"bodyPreview":"Dana, this is the time you selected for our orientation. Please bring the notes I sent you.",
"body":{
"contentType":"text",
"content":"Dana, this is the time you selected for our orientation. Please bring the notes I sent you.\r\n"
}
}
Example 3: Get an event that specifies more than one location
Request
The following example shows getting an event that specifies more than one location. The request specifies a $select
query parameter
to return specific properties.
GET https://graph.microsoft.com/beta/me/events/AAMkADAGAADDdm4NAAA=?$select=subject,body,bodyPreview,organizer,attendees,start,end,location,locations
Response
The following example shows the response. The locations property includes details for the 3 locations that the event is organized for.
Because the request does not specify any Prefer: outlook.timezone
or Prefer: outlook.body-content-type
header,
the start and end properties are displayed in the default UTC time zone, and the body is in the default HTML format.
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context":"https://graph.microsoft.com/beta/$metadata#users('d1a2fae9-db66-4cc9-8133-2184c77af1b8')/events(subject,body,bodyPreview,organizer,attendees,start,end,location,locations)/$entity",
"@odata.etag":"W/\"y53lbKh6jkaxHzFwGhgyxgAAw5zhug==\"",
"id":"AAMkADAGAADDdm4NAAA=",
"iCalUId": "040000008200E00074=",
"uid": "040000008200E00074C=",
"subject":"Plan summer company picnic",
"bodyPreview":"Let's kick-start this event planning!",
"body":{
"contentType":"html",
"content":"<html>\r\n<head>\r\n</head>\r\n<body>\r\nLet's kick-start this event planning!\r\n</body>\r\n</html>\r\n"
},
"start":{
"dateTime":"2017-08-30T11:00:00.0000000",
"timeZone":"UTC"
},
"end":{
"dateTime":"2017-08-30T12:00:00.0000000",
"timeZone":"UTC"
},
"location":{
"displayName":"Conf Room 3; Fourth Coffee; Home Office",
"locationType":"default",
"uniqueId":"Conf Room 3; Fourth Coffee; Home Office",
"uniqueIdType":"private"
},
"locations":[
{
"displayName":"Conf Room 3",
"locationType":"default",
"uniqueIdType":"unknown"
},
{
"displayName":"Fourth Coffee",
"locationType":"default",
"uniqueId":"Fourth Coffee",
"uniqueIdType":"private",
"address":{
"type":"unknown",
"street":"4567 Main St",
"city":"Redmond",
"state":"WA",
"countryOrRegion":"US",
"postalCode":"32008"
},
"coordinates":{
"latitude":47.672,
"longitude":-102.103
}
},
{
"displayName":"Home Office",
"locationType":"default",
"uniqueIdType":"unknown"
}
],
"attendees":[
{
"type":"required",
"status":{
"response":"none",
"time":"0001-01-01T00:00:00Z"
},
"emailAddress":{
"name":"Dana Swope",
"address":"DanaS@contoso.com"
}
},
{
"type":"required",
"status":{
"response":"none",
"time":"0001-01-01T00:00:00Z"
},
"emailAddress":{
"name":"Alex Wilber",
"address":"AlexW@contoso.com"
}
}
],
"organizer":{
"emailAddress":{
"name":"Adele Vance",
"address":"AdeleV@contoso.com"
}
}
}
Example 4: Expand a series master event
Request
The following example shows expanding a series master event of a recurring series with exceptions and cancelled occurences. The request specifies a $select
query parameter to return specific properties.
GET https://graph.microsoft.com/beta/me/events/AAMkADAGAADDdm4NAAA=?$select=subject,start,end,occurrenceId,exceptionOccurrences,cancelledOccurrences&$expand=exceptionOccurrences
Response
The GET operation returns the selected properties for the series master event. Specifically, for events in the exceptionOccurrences collection, the operation returns the id property, and the applicable, selected properties (subject, start, end, occurrenceId). As for events in the cancelledOccurrences collection, because the events no longer exist, the operation returns only their occurrenceId property values.
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context":"https://graph.microsoft.com/beta/$metadata#users('d1a2fae9-db66-4cc9-8133-2184c77af1b8')/events(subject,start,end,occurrenceId,exceptionOccurrences,cancelledOccurrences)/$entity",
"@odata.etag":"W/\"y53lbKh6jkaxHzFwGhgyxgAAw5zhug==\"",
"id":"AAMkADAGAADDdm4NAAA=",
"iCalUId": "040000008200E00074=",
"uid": "040000008200E00074C=",
"subject": "Daily stand-up",
"cancelledOccurrences": [
"OID.AAMkADAGAADDdm4NAAA=.2020-04-30",
"OID.AAMkADAGAADDdm4NAAA=.2020-05-07",
"OID.AAMkADAGAADDdm4NAAA=.2020-05-14"
],
"occurrenceId": null,
"start": {
"dateTime": "2020-04-23T11:30:00.0000000",
"timeZone": "UTC"
},
"end": {
"dateTime": "2020-04-23T12:00:00.0000000",
"timeZone": "UTC"
},
"exceptionOccurrences": [
{
"id": "AAMkADM0ZGRhMjdjLTA==",
"Subject": "SM update 24",
"occurrenceId": "OID.AAMkADAGAADDdm4NAAA=.2020-05-21",
"start": {
"dateTime": "2020-05-21T11:30:00.0000000",
"timeZone": "UTC"
},
"end": {
"dateTime": "2020-05-21T12:00:00.0000000",
"timeZone": "UTC"
}
}
]
}
Related content
Feedback
https://aka.ms/ContentUserFeedback.
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see:Submit and view feedback for