Microsoft Graph API Patterns

Microsoft Graph API Patterns

Overview

Microsoft Graph is the unified REST API surface for all M365 services (users, mail, calendar, Teams, OneDrive, security). All M365 MCP tools ultimately make Graph calls. Understanding Graph's OData query syntax, pagination model, throttling behavior, and auth patterns is essential for building reliable M365 workflows.

Authentication

Token Scope for MSP Operations

The Softeria MS-365 MCP server (--org-mode) accepts a Bearer token per request via the Authorization header. The token must be obtained from Microsoft Entra using the common endpoint (multi-tenant) with the following scopes:

Scope	Purpose
https://graph.microsoft.com/.default	All Graph permissions granted to app
openid	ID token for tenant ID extraction
profile	User profile claims
offline_access	Refresh token for session persistence

Base URL

All Graph API calls use:

https://graph.microsoft.com/v1.0/

Beta features (preview, subject to change):

https://graph.microsoft.com/beta/

OData Query Parameters

Parameter	Purpose	Example
$select	Return only specified fields	$select=id,displayName,email
$filter	Filter results	$filter=accountEnabled eq true
$search	Full-text search (mailboxes, users)	$search="displayName:Smith"
$orderby	Sort results	$orderby=displayName asc
$top	Limit results per page	$top=100
$skip	Skip N results	$skip=100
$count	Include total count	$count=true
$expand	Include related entities	$expand=manager

Filter Syntax

eq        equal             $filter=accountEnabled eq true
ne        not equal         $filter=jobTitle ne 'Manager'
gt/lt     greater/less      $filter=createdDateTime gt 2024-01-01T00:00:00Z
ge/le     >=, <=            same but inclusive
and/or    logical           $filter=dept eq 'IT' and accountEnabled eq true
not       negation          $filter=not startsWith(mail,'test')
startsWith prefix match     $filter=startsWith(displayName,'J')
endsWith  suffix match      $filter=endsWith(mail,'@contoso.com')
contains  substring         $filter=contains(jobTitle,'Manager')
any/all   collection ops    $filter=assignedLicenses/any(x:x/skuId eq '<guid>')

Advanced Queries (Require ConsistencyLevel: eventual)

Some filters require the ConsistencyLevel: eventual header and $count=true:

GET /v1.0/users?$filter=assignedLicenses/$count eq 0&$count=true&ConsistencyLevel: eventual

Pagination

Graph uses server-side pagination. Always check for @odata.nextLink in responses.

Standard Pagination Loop

1. Make initial request with $top=100
2. If response contains @odata.nextLink → follow it
3. Repeat until no @odata.nextLink

Response with more pages:

{
  "@odata.context": "...",
  "@odata.nextLink": "https://graph.microsoft.com/v1.0/users?$skiptoken=abc123",
  "value": [...]
}

Response — last page:

{
  "@odata.context": "...",
  "value": [...]
}

The Softeria MCP server handles pagination automatically for supported operations.

Delta Queries (Incremental Sync)

Delta queries return only changed items since the last sync — ideal for regular polling.

Initial Delta Request

GET /v1.0/users/delta?$select=id,displayName,userPrincipalName,accountEnabled

Response includes a @odata.deltaLink after the last page — store this.

Subsequent Delta Requests

GET {deltaLink}

Returns only users added, modified, or deleted since the delta token was issued. Deleted users have "@removed": { "reason": "deleted" } in the response.

Throttling and Retry

Graph throttles requests at both per-app and per-tenant levels. Throttled responses return 429 Too Many Requests.

Retry-After Header

Always check the Retry-After header on 429:

HTTP/1.1 429 Too Many Requests
Retry-After: 15

Wait the specified seconds before retrying.

Graph Throttle Limits (Approximate)

Resource	Limit
Per app per tenant	10,000 req/10 min
Per user	3,000 req/10 min
Mail search	10 concurrent
Reports	1 req/15 min per report

Best Practices

1. Use $select to request only needed fields (reduces payload + throttle pressure)
2. Use $filter server-side rather than fetching all and filtering in code
3. Use delta queries for sync operations instead of polling all items
4. Batch unrelated requests (see below) to reduce round-trips

Batch Requests

Combine up to 20 independent Graph calls into one HTTP request:

POST /v1.0/$batch
Content-Type: application/json

{
  "requests": [
    {
      "id": "1",
      "method": "GET",
      "url": "/users/[email protected]?$select=displayName,accountEnabled"
    },
    {
      "id": "2",
      "method": "GET",
      "url": "/users/[email protected]?$select=displayName,accountEnabled"
    }
  ]
}

Response:

{
  "responses": [
    { "id": "1", "status": 200, "body": { "displayName": "Alice", "accountEnabled": true } },
    { "id": "2", "status": 200, "body": { "displayName": "Bob", "accountEnabled": false } }
  ]
}

Use for fetching details on multiple known user IDs simultaneously.

Common Error Codes

HTTP	Code	Meaning	Fix
400	Request_BadRequest	Malformed OData filter	Check filter syntax
401	InvalidAuthenticationToken	Token expired or malformed	Re-authenticate
403	Authorization_RequestDenied	Missing Graph permission	Add scope, re-consent
404	Request_ResourceNotFound	Object doesn't exist	Check GUID/UPN
429	ActivityLimitReached	Throttled	Wait Retry-After seconds
500	ServiceInternalServerError	Graph outage	Retry with backoff
503	ServiceUnavailable	Transient	Retry with backoff

Useful Graph Explorer

For testing queries interactively: https://developer.microsoft.com/graph/graph-explorer

Log in with a test M365 account to explore API responses before writing code.

Related Skills

• M365 Users - User query examples
• M365 Security - Audit log query patterns
• M365 Mailboxes - Search and KQL syntax