Throttling coming to Outlook API and Microsoft Graph

Update 12/4/17: Updated the post with the current limits.

On April 21, we will be enabling throttling on the Outlook REST APIs (accessed via https://outlook.office.com/api or https://outlook.office365.com/api), and on the Outlook-related endpoints of the Microsoft Graph (accessed via https://graph.microsoft.com). We wanted to give developers some advanced warning to make sure you were prepared!

What's the limit?

The limit is 10000 requests per 10-minute period, per user (or group), per app ID. This means that your app can make at most 10000 requests to a single user's mailbox in a 10-minute period. If your app is requesting data from multiple users simultaneously, requests to one user do not impact the limit for another user.

What APIs are subject to this limit?

Outlook APIs

All APIs accessed via https://outlook.office.com/api or https://outlook.office365.com/api, including:

Microsoft Graph

Only the Outlook-related APIs in the Microsoft Graph are subject to this limit. Microsoft Graph requests to non-Outlook resources (such as OneDrive files) would not count against this limit. The following resources (and their child resources) are subject to the limit:

Can I track my usage?

Each response from the API will contain specific headers that can help you track your current state in regards to the rate limit.

Note: Only the Outlook REST API endpoints return these rate limit tracking headers. The Microsoft Graph endpoint does not return these headers.

Header name Description
Rate-Limit-Limit The maximum number of requests that the app is permitted to make per minute for the current user or group
Rate-Limit-Remaining The number of requests remaining in the current rate limit window
Rate-Limit-Reset The time at which the current rate limit window resets in UTC time

What happens if my app exceeds the limit?

You'll get a 429 response back from the server. The response will include a Retry-After header, which will specify the number of seconds your app must wait until it can make more requests for the particular user or group. It will also include a Rate-Limit-Reason header with a human-readable string that articulates the reason for the throttled request.

How do I avoid being throttled?

If your app is currently making more than the allowed number of requests, there may be some ways that you can reduce the number of requests without reducing the amount of data your app is accessing. Some general tips to reduce requests are:

  • Increasing page size: Using the $top parameter to increase the number of items returned per page when requesting a set of items. The default page size if the $top parameter is omitted is 10, which isn't very efficient if you're requesting a large number of items. You can increase this limit up to 1000.
  • Reduce number of GET for single items: As much as possible, get the data your app needs from lists (such as GET /me/messages) rather than requesting each individual entity (such as GET /me/messages/{message-id}). Using the $select parameter to request the fields your app needs can help you control what data is returned back in lists.

Call to action

Based on the usage rates we've seen to date, we believe that most apps out there will not exceed the limit. However, we encourage you to review your app and determine if you are likely to exceed the limits. If so, you should look at ways to reduce the number of requests or make sure you have error handling in place to handle 429 responses and retry in an appropriate amount of time.

We will be publishing more detailed documentation on these limits in the near future.