Microsoft 365 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.

Anti-triggers

This skill teaches you to compose Graph calls by hand. Two neighbouring plugins cover the same tenant with almost identical vocabulary, and choosing the wrong one is the most common routing mistake in the Microsoft estate:

• A read-only question about one tenant — "how many users", "who has no MFA registered", "which licences are unassigned". The Graph Enterprise MCP answers these from a vetted query catalogue, so nobody hand-writes a $filter; use the microsoft-graph plugin's microsoft-graph-querying skill. Hand-writing a Graph URL when that server is connected is the exact error pattern it exists to prevent.
• Anything spanning more than one customer tenant — fleet-wide standards, BPA drift, GDAP, or a packaged action such as offboard / reset MFA / revoke sessions. Use the cipp plugin, which carries the multi-tenant scope and per-tenant audit trail this plugin does not.
• A tenant that authenticates but returns nothing — that is an app registration and admin-consent problem, not a query-syntax problem; use microsoft-graph-connection.

The short rule: ask one tenant → microsoft-graph; change one tenant → this plugin; do either across the fleet → cipp.

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:

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

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)

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/user1@contoso.com?$select=displayName,accountEnabled"
    },
    {
      "id": "2",
      "method": "GET",
      "url": "/users/user2@contoso.com?$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

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