Throttling coming to Outlook API and Microsoft Graph


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 60 requests per minute, per user (or group), per app ID. This means that your app can make at most 60 requests to a single user’s mailbox in a minute. 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.

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 60 requests per minute per user or group, 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.

Comments (6)

  1. Yairrr says:

    Thanks for the update, it’s great to finally have the limits written down clearly with a way to know the status.
    How will it work alongside the current more vague limitations?
    I noticed there is some throttling already, except instead of returning a negative answer, i get the answer very slowly until my app decides it’s too slow to work with.
    This seems to be per user and it may or may not be a shared limitation with other APIs like EWS onedrive etc.
    Can you comment on that?

    1. I don’t know any specifics about it, this is the first I’m hearing of any such limit. I’ll see what I can find out.

      1. Ok, I chatted with our devs and from what you’re describing, that sounds like a shared limit with EWS that is currently in place. The new limiting mechanism described here will replace this scheme, so it should be more transparent and predictable.

        1. Yairrr says:

          Fantastic! thanks

  2. Garima says:

    Hi Jason, little bit off topic here but I am trying to find a sample where I can query outlook mail api in javascript using adal. I need to use this code in script editor web part of sharepoint. Could you point me to the right direction.

Skip to main content