calendar: getSchedule
Namespace: microsoft.graph
Get the free/busy availability information for a collection of users, distributions lists, or resources (rooms or equipment) for a specified time period.
This API is available in the following national cloud deployments.
Global service | US Government L4 | US Government L5 (DOD) | China operated by 21Vianet |
---|---|---|---|
✅ | ✅ | ✅ | ✅ |
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, Calendars.ReadWrite |
Delegated (personal Microsoft account) | Not supported. | Not supported. |
Application | Calendars.ReadBasic | Calendars.Read, Calendars.ReadWrite |
HTTP request
POST /me/calendar/getSchedule
POST /users/{id|userPrincipalName}/calendar/getSchedule
Request headers
Name | Type | Description |
---|---|---|
Authorization | string | Bearer {token}. Required. Learn more about authentication and authorization. |
Content-Type | string | Nature of the data in the body of an entity, which is application/json. 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. |
Request body
In the request body, provide a JSON object with the following parameters.
Property | Type | Description |
---|---|---|
availabilityViewInterval | Int32 | Represents the duration of a time slot in an availabilityView in the response. The default is 30 minutes, minimum is 5, maximum is 1440. Optional. |
endTime | dateTimeTimeZone | The date, time, and time zone that the period ends. |
schedules | String collection | A collection of SMTP addresses of users, distribution lists, or resources to get availability information for. |
startTime | dateTimeTimeZone | The date, time, and time zone that the period starts. |
Response
If successful, this method returns a 200 OK
response code and a collection of scheduleInformation objects for each object in the schedules
parameter.
Note: When the user's calendar has a time slot that contains more than 1000 entries, a
5006
response code with the message "The result set contains too many calendar entries. The allowed size is 1000; the actual size is ..." will be returned. For details, see KB 2962513.
Examples
Request
The following example gets the availability information for two users for the specified date, time, and time zone.
POST https://graph.microsoft.com/v1.0/me/calendar/getSchedule
Prefer: outlook.timezone="Pacific Standard Time"
Content-Type: application/json
{
"schedules": ["[email protected]", "[email protected]"],
"startTime": {
"dateTime": "2019-03-15T09:00:00",
"timeZone": "Pacific Standard Time"
},
"endTime": {
"dateTime": "2019-03-15T18:00:00",
"timeZone": "Pacific Standard Time"
},
"availabilityViewInterval": 60
}
Response
The following example shows the response. Note: The response object shown here might be shortened for readability.
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(microsoft.graph.scheduleInformation)",
"value": [
{
"scheduleId": "[email protected]",
"availabilityView": "000220000",
"scheduleItems": [
{
"isPrivate": false,
"status": "busy",
"subject": "Let's go for lunch",
"location": "Harry's Bar",
"start": {
"dateTime": "2019-03-15T12:00:00.0000000",
"timeZone": "Pacific Standard Time"
},
"end": {
"dateTime": "2019-03-15T14:00:00.0000000",
"timeZone": "Pacific Standard Time"
}
}
],
"workingHours": {
"daysOfWeek": [
"monday",
"tuesday",
"wednesday",
"thursday",
"friday"
],
"startTime": "08:00:00.0000000",
"endTime": "17:00:00.0000000",
"timeZone": {
"name": "Pacific Standard Time"
}
}
},
{
"scheduleId": "[email protected]",
"availabilityView": "200220010",
"scheduleItems": [
{
"status": "busy",
"start": {
"dateTime": "2019-03-15T08:30:00.0000000",
"timeZone": "Pacific Standard Time"
},
"end": {
"dateTime": "2019-03-15T09:30:00.0000000",
"timeZone": "Pacific Standard Time"
}
},
{
"status": "busy",
"start": {
"dateTime": "2019-03-15T12:00:00.0000000",
"timeZone": "Pacific Standard Time"
},
"end": {
"dateTime": "2019-03-15T14:00:00.0000000",
"timeZone": "Pacific Standard Time"
}
},
{
"status": "tentative",
"start": {
"dateTime": "2019-03-15T12:00:00.0000000",
"timeZone": "Pacific Standard Time"
},
"end": {
"dateTime": "2019-03-15T13:00:00.0000000",
"timeZone": "Pacific Standard Time"
}
},
{
"status": "busy",
"start": {
"dateTime": "2019-03-15T13:00:00.0000000",
"timeZone": "Pacific Standard Time"
},
"end": {
"dateTime": "2019-03-15T14:00:00.0000000",
"timeZone": "Pacific Standard Time"
}
},
{
"status": "tentative",
"start": {
"dateTime": "2019-03-15T16:00:00.0000000",
"timeZone": "Pacific Standard Time"
},
"end": {
"dateTime": "2019-03-15T17:00:00.0000000",
"timeZone": "Pacific Standard Time"
}
}
],
"workingHours": {
"daysOfWeek": [
"monday",
"tuesday",
"wednesday",
"thursday",
"friday"
],
"startTime": "08:00:00.0000000",
"endTime": "17:00:00.0000000",
"timeZone": {
"@odata.type": "#microsoft.graph.customTimeZone",
"bias": 480,
"name": "Customized Time Zone",
"standardOffset": {
"time": "02:00:00.0000000",
"dayOccurrence": 1,
"dayOfWeek": "sunday",
"month": 11,
"year": 0
},
"daylightOffset": {
"daylightBias": -60,
"time": "02:00:00.0000000",
"dayOccurrence": 2,
"dayOfWeek": "sunday",
"month": 3,
"year": 0
}
}
}
}
]
}