Skip to content

Microsoft Graph rate limits ​

Atlas reads and writes Microsoft 365 only through Microsoft Graph, and Microsoft Graph limits how many requests an app may send. When a backup goes over a limit, Microsoft Graph answers 429 Too Many Requests with a Retry-After header that says how long to wait. Atlas pauses, waits, and retries on its own.

Occasional throttling during a large first backup is normal and needs no action. What you control is how many jobs run at once, and the limits decide how far that helps:

WorkloadBudgetRunning more jobs in parallel
OutlookOne per mailboxAdds capacity. 50 mailbox backups draw from 50 budgets
OneDrive, SharePointOne per tenant, shared by every drive and siteHelps only while the tenant budget has headroom
TeamsOne per tenant, plus limits per team and channelAtlas paces requests itself. --concurrency sets channels in parallel
Mailbox discoveryOne per tenantMatters only when many tenants list mailboxes at once

The limits below are the values Atlas builds into GRAPH_SERVICE_LIMITS, with Microsoft's source linked for each.

Spacing runs with the SDK ​

Every SDK result reports the requests it used in graphCost, and a failed run still reports what it consumed. A scheduler can use it to keep the next run of a mailbox out of the current throttling window:

ts
import { createAtlasInstance, getGraphCost, GRAPH_SERVICE_LIMITS } from '@wisecom/atlas-sdk';

const atlas = createAtlasInstance(config); // AtlasInstanceConfig, see the SDK reference

let graphCost;
let failure: unknown;
try {
  const result = await atlas.outlook.backup('<mailbox-id>');
  graphCost = result.graphCost;
} catch (err) {
  failure = err;
  graphCost = getGraphCost(err); // a failed run still consumed quota
}

const used = graphCost?.byService.outlook?.requests ?? 0;
// Requests from this run leave the 10-minute sliding window within one window of being sent.
const cooldownMs = used > 0 ? GRAPH_SERVICE_LIMITS.outlook.windowDurationMs : 0;
// Store the cooldown before rethrowing, so a failed run still delays the next one.
await saveCooldown('<mailbox-id>', Date.now() + cooldownMs); // your scheduler's store
if (failure !== undefined) throw failure;

graphCost is measured at the HTTP transport. Each @odata.nextLink page and each retry attempt counts as its own request, so a cooldown computed from it reflects quota actually used. A run that threw usually used more quota than one that finished, so apply the cooldown in both cases. The SDK reference documents AtlasInstanceConfig and the full OperationCost type.

How Microsoft Graph throttles ​

Each request is checked against two layers. The first limit reached returns 429 Too Many Requests:

LayerScopeLimit
GlobalPer app, across all tenants130,000 requests per 10 seconds
Service-specificPer pool, see belowSeparate budget per pool

The global limit matters only for an app running hundreds of tenants at once. For most deployments the service pools are the constraint. Each pool has its own budget, and using one does not reduce another. Atlas uses four:

PoolScopeCost modelUsed by
OutlookPer app, per mailboxFlat (1 request = 1)Mail backup and restore
SharePoint / OneDrivePer app, per tenantResource units (1 to 5 RU)OneDrive and SharePoint backup
Identity (Microsoft Entra ID)Per app, per tenantResource units (1 to 5 RU)Mailbox discovery
TeamsPer app, per tenant, plus per team or channelFlat (1 request = 1)Teams channel backup

A throttled request still counts toward the budget.

Throttle handling ​

When Microsoft Graph throttles a request, Atlas pauses every request that draws on the same budget, not only the one that was refused. This is what slows the instance down: concurrency is fixed and a 429 does not lower it.

  1. The pool cools down. Atlas's throttle coordinator starts a cooldown for the Retry-After window, or 30 seconds when Microsoft Graph sends none. Every request to that budget waits for it before it is sent, including retry attempts already in progress.
  2. The throttled call retries. It waits out the cooldown and tries again, up to 12 retries. Without a Retry-After, it backs off exponentially, up to 5 minutes per wait.
  3. Requests resume gradually. When the cooldown ends, each waiting request resumes after its own random delay, so the pool does not return to Microsoft Graph in one burst and draw the next 429.
Budget throttledWhat pauses
One Outlook mailboxOnly that mailbox's requests. Other mailboxes keep sending
SharePoint / OneDriveEvery drive and site request of the instance, because they share one tenant budget
IdentityEvery identity request of the instance
One teamOnly that team's requests. Listing the tenant's teams has no team, so a 429 there pauses the whole Teams pool

A cooldown never crosses pools. Overlapping cooldowns do not add up: the longest one wins.

Throttle timing in detail
ParameterValue
Cooldown without Retry-After30 s
Maximum retries12, so at most 13 HTTP attempts per call
Backoff cap per wait5 minutes
Waiting budget per call24 minutes. After that the call starts no new wait, but a wait already started runs in full. Time spent inside each request does not count
Longest Retry-After honoured1 hour. A longer value fails the call with a ThrottledError naming the value, and the pool still cools down for the hour
Release delay after a cooldownRandom, up to a tenth of the cooldown, kept between 1 and 5 s. A 6-minute cooldown releases its requests over 5 s

The release delay is only ever added, so nothing is sent before the Retry-After Microsoft Graph asked for. The cooldown starts on the first throttled response, so calls already in a retry loop see it between attempts.

Retries happen in one layer only. The Graph SDK's own retry handler is disabled, because running both layers would multiply the retries.

What the coordinator covers ​

Every request made through a Graph connector is coordinated, including mailbox discovery and user resolution on the identity pool, and Outlook restore.

OneDrive and SharePoint file downloads (whole or in ranges) and resumable upload chunks use pre-authenticated URLs instead of the Graph client. Atlas still makes each attempt wait for the sharepoint_onedrive cooldown before it is sent, and raises the cooldown on a 429, or a 503 with Retry-After. Their own retry backoff still applies, see File transfers.

Several processes for one tenant ​

The default coordinator lives in memory and covers one Atlas instance. A host that runs several processes for the same tenant can pass its own throttleCoordinator, so a 429 in one process pauses the others. A host coordinator fails open: if its shared store is unreachable, requests proceed on their own backoff and a warning is logged. See Concurrent operations.

Outlook pool ​

Official source: Outlook service limits

Outlook limits apply per app ID per mailbox. Each request costs 1, whatever the endpoint or method.

LimitMicrosoftAtlas
API requests per 10-minute window10,000Paces each mailbox at 9,600 (96%), leaving headroom for requests in flight
Concurrent requests per mailbox44
Upload body size per 5-minute window (POST, PATCH, PUT)150 MB

Microsoft Graph processes at most four requests from a $batch at a time, and a dependsOn chain runs them one at a time. Each request inside a batch counts against the window on its own, so Atlas charges its pacing one unit per request in the batch, not one per round trip. graphCost counts the same way, so reaction capture costs one request per stored message in both. A retried batch resends only the messages still pending, and graphCost counts those again.

Requests in the Outlook pool ​

graphCost.requestsByType labels each request with the operation that issued it:

requestsByType labelMicrosoft Graph endpointCost
list_foldersGET /users/{id}/mailFolders, /mailFolders/{wellKnownName}1 per folder page, plus well-known folder reads
delta_syncGET /users/{id}/mailFolders/{id}/messages/delta1 per page
fetch_messageGET /users/{id}/messages/{id}1
fetch_mimeGET /users/{id}/messages/{id}/$value1
fetch_extended_propertiesPOST /$batch of up to 20 chained GET /users/{id}/messages/{id}?$expand=singleValueExtendedProperties(...)1 per message, 1 round trip per 20 messages
fetch_attachmentsGET /users/{id}/messages/{id}/attachments1
create_folderPOST /users/{id}/mailFolders1
create_messagePOST /users/{id}/mailFolders/{id}/messages1
add_attachmentPOST /users/{id}/messages/{id}/attachments1, plus upload bytes
create_upload_sessionPOST /users/{id}/messages/{id}/attachments/createUploadSession1
upload_chunkPUT {upload_url}1, plus upload bytes
count_folder_messagesGET /users/{id}/mailFolders/{id}?$select=totalItemCount1
list_folder_messagesGET /users/{id}/mailFolders/{id}/messages1

Restore also records find_child_folder and read_well_known_folder for its folder lookups.

SharePoint and OneDrive pool ​

Official source: Avoid getting throttled or blocked in SharePoint Online

This pool is per app, per tenant. Every call is charged in resource units (RU).

The budget is per tenant, not per user. Running N drive backups in parallel for one tenant does not add capacity the way N mailbox backups do, because they draw on the same budget. Parallel drive jobs shorten a run only while the budget has headroom. Once Microsoft Graph throttles, the shared cooldown pauses all of them together.

Drive cost is recorded at 1 RU per request

Atlas records every SharePoint and OneDrive request under byService.sharepoint_onedrive in graphCost at 1 RU, without Microsoft's per-operation costs. The totals therefore undercount what Microsoft charges for list, delta-without-token, and permission calls. Use the Microsoft limits below for scheduling, not the recorded RU.

Resource unit costs ​

OperationCost
Single-item GET, delta with a token1 RU
Multi-item list or search, delta without a token2 RU
Permission operations, $expand=permissions5 RU

Microsoft can change these costs. GRAPH_SERVICE_LIMITS.sharepoint_onedrive holds the values Atlas uses.

Per-app, per-tenant limits ​

The limits scale with the tenant's license count.

LicensesRU per minuteRU per 24 hours
0 to 1,0001,2501,200,000
1,001 to 5,0002,5002,400,000
5,001 to 15,0003,7503,600,000
15,001 to 50,0005,0004,800,000
50,000 and over6,2506,000,000

Tenant-level limits (all apps combined) ​

LicensesRU per 5 minutes
0 to 1,00018,750
1,001 to 5,00037,500
5,001 to 15,00056,250
15,001 to 50,00075,000
50,000 and over93,750

User-level and bandwidth limits ​

ScopeLimit
Per user3,000 requests per 5 minutes
Per user50 GB ingress and 100 GB egress per hour
Per app, per tenant400 GB ingress and 400 GB egress per hour

Throttle responses ​

ResponseMeaning
429 Too Many RequestsThe app exceeded its rate limit. Includes Retry-After
503 Service UnavailableService-level load spike. Includes Retry-After

An app that keeps exceeding its limits can be blocked, and receives 503 until the block lifts. Microsoft announces blocks through the Microsoft 365 Message Center.

SharePoint also sends RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers (IETF draft-03, preview) once an app uses 80% of its one-minute RU budget. Atlas does not read these headers. See RateLimit headers.

Identity pool (Microsoft Entra ID) ​

Official source: Identity and access service limits

Atlas reads from this pool only for mailbox discovery and existence checks. These run at job start, so they seldom matter at small scale. They matter when many tenants list mailboxes at once.

The pool is per app, per tenant, with a global per-app limit across all tenants. Each call has a base RU cost, adjusted by query parameters.

Tenant tierUsersRU per 10 seconds
SUnder 503,500
M50 to 5005,000
LOver 5008,000
Global per-app limitValue
Read150,000 RU per 20 seconds
Write35,000 requests per 5 minutes

Write quota per app and tenant is 3,000 requests per 2 minutes 30 seconds. Write requests per tenant across all apps are capped at 18,000 per 5 minutes.

EndpointBase cost
GET /users2 RU
GET /users/{id}1 RU
GET /reports/getMailboxUsageDetail1 RU
Other read paths1 RU

$select reduces the cost by 1 RU, $expand adds 1 RU, and $top below 20 reduces it by 1 RU. Atlas uses $select on user listing calls, so each /users page costs about 1 RU.

Teams pool ​

Official source: Microsoft Teams service limits

This pool is per app, per tenant, with extra limits per team and per channel. Each call costs one request.

EndpointPer app, per tenantPer team or channel
Channel message reads20 per second1 per second per channel
Team reads30 per second4 per second per team

Atlas paces Teams requests at 80% of these limits, so Microsoft Graph seldom has to throttle them. See Teams pacing. A 429 from the Teams pool pauses only the team it came from, and the tenant's other teams keep running. Listing the tenant's teams has no team, so a 429 there pauses the whole Teams pool. A Teams 429 never pauses another pool. See Throttle handling.

Summary ​

PoolScopeCost modelConstraint
OutlookPer mailboxFlatPrimary limit for mail backup and restore
SharePoint / OneDrivePer tenantResource unitsCoordinate drive jobs per tenant
IdentityPer tenantResource unitsMatters only for discovery at scale
TeamsPer tenant, plus per team or channelFlatLimits for busy channels and teams
GlobalPer appFlatMatters only with hundreds of active tenants

For scheduling:

  • Outlook is the most parallel pool. N mailbox backups use N budgets.
  • Treat all drive jobs for one tenant as sharing one budget.
  • Identity cost is small for individual jobs. Watch it only for tenant-wide discovery.

Official Microsoft documentation ​

See also ​