# SharePoint Delta Sync: Graph API Delta Queries & AI Agent Indexing SharePoint delta sync uses Microsoft Graph delta queries to track incremental file additions, edits, and deletions within a document library using resumable delta tokens. By querying the driveItem delta endpoint and following nextLink pagination, systems capture document changes without full library rescans. Understanding delta token expiration and HTTP 410 Gone handling ensures background indexing keeps AI agents synchronized with enterprise storage. Source: https://fast.io/resources/sharepoint-delta-sync/ Author: [Derek Labian](https://fast.io/authors/derek-labian/) Last reviewed: 2026-11-07 ## How SharePoint Delta Sync Tracks Document Library Changes Enterprise document libraries in SharePoint change constantly as engineering, legal, and operations teams add, edit, and reorganize working documents. Pointing an autonomous AI agent directly at a large document library to inspect every folder on a recurring loop rapidly exhausts API quotas, triggers request throttling, and degrades retrieval latency. SharePoint delta sync uses Microsoft Graph delta queries to track incremental file additions, edits, and deletions within a document library using resumable delta tokens, replacing recursive folder enumeration with stateful change tracking. When an AI agent needs access to enterprise knowledge stored in Microsoft 365, scanning directory structures by sending recursive calls to folder child endpoints creates an unsustainable overhead. A document library with thousands of files across deep folder trees requires dozens of sequential round trips simply to discover whether a single file changed. Microsoft Graph delta queries eliminate that crawl by maintaining a server-side change log that applications query with point-in-time tokens. ### The Mechanics of Microsoft Graph Delta Queries The Microsoft Graph API exposes change tracking directly on the `driveItem` resource through the `delta` function. Rather than checking individual folder contents, an application targets a document library drive or a specific subfolder path: * **SharePoint Document Library Root**: `GET https://graph.microsoft.com/v1.0/drives/{drive-id}/root/delta` * **Specific Site Document Drive**: `GET https://graph.microsoft.com/v1.0/sites/{site-id}/drive/root/delta` * **Targeted Subfolder Hierarchy**: `GET https://graph.microsoft.com/v1.0/drives/{drive-id}/items/{folder-id}/delta` Microsoft Graph delta queries operate in 4 key steps: 1. **Initial delta request**: The client initiates tracking by issuing an initial GET request to the target delta endpoint without a state token. 2. **Page token iteration**: The service returns an initial page of drive items alongside an `@odata.nextLink` URL containing a continuation token. The client loops through these pages sequentially until all baseline items are retrieved. 3. **Delta token storage**: On the final page of the collection, Microsoft Graph replaces `@odata.nextLink` with an `@odata.deltaLink` URL containing an opaque delta token. The client persists this URL in durable storage. 4. **Scheduled change query**: When the client checks for changes during subsequent synchronization cycles, it requests the saved `@odata.deltaLink` URL directly. Microsoft Graph evaluates the token and returns only the file additions, modifications, and deletions that occurred since the token was issued. Microsoft Graph delta queries track incremental changes in a drive hierarchy over time, returning an @odata.deltaLink on the final page to retrieve subsequent changes. ### Recursive Directory Crawling vs. Delta Query Synchronization Comparing traditional folder crawling with token-based delta synchronization illustrates why delta queries are essential for real-world agent operations: | Synchronization Dimension | Recursive Directory Crawl (`/children`) | Delta Query Sync (`/delta`) | |---|---|---| | Request Target | Present snapshot of each folder | Stateful change log across hierarchy | | Initial Baseline Cost | One API call per folder | Batched paged responses across drive | | Incremental Polling Cost | Hundreds of requests across directory tree | Single request during low-activity windows | | Deletion Detection | Expensive diff against local database | Explicit deletion records with `@removed` facet | | Rate Limit Exposure | High risk of HTTP 429 throttling | Minimal request footprint during sync runs | | Agent Readiness | High latency before context updates | Rapid incremental indexing | Traditional folder walks inspect static snapshots of child items. If an enterprise user deletes a subfolder or renames a specification document deep inside a nested structure, an agent walking the tree must traverse every ancestor folder before discovering the modification. Delta queries flatten hierarchy traversal into a single unified change stream. ## Managing Pagination and Change Feeds with DriveItem Delta Queries Understanding the mechanics of `sharepoint driveitem delta query` and `sharepoint graph api delta sync` requires managing two distinct pagination indicators: the continuation link (`@odata.nextLink`) and the state completion link (`@odata.deltaLink`). When an application calls `/drives/{drive-id}/root/delta`, the response contains an array of `driveItem` objects representing files, folders, and packages. If the number of modified items exceeds the page size or if the baseline inventory is still being returned, Microsoft Graph includes an `@odata.nextLink` property in the response payload: ```json { "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(driveItem)", "@odata.nextLink": "https://graph.microsoft.com/v1.0/drives/b!AbCdEf123/root/delta?$skiptoken=X'1234567890ABCDEF'", "value": [ { "id": "01ABCDEF23456789", "name": "architecture-diagram.pdf", "size": 2458900, "lastModifiedDateTime": "2026-11-06T14:32:00Z", "file": { "mimeType": "application/pdf" }, "parentReference": { "driveId": "b!AbCdEf123", "id": "01ROOTFOLDER123" } } ] } ``` The application must follow every `@odata.nextLink` until the property is absent. The final response in the pagination chain contains `@odata.deltaLink`: ```json { "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(driveItem)", "@odata.deltaLink": "https://graph.microsoft.com/v1.0/drives/b!AbCdEf123/root/delta?$deltatoken=aTE0NjQ5MjQ...", "value": [] } ``` Persisting the entire `@odata.deltaLink` string is critical. The embedded `$deltatoken` parameter encodes server-side cursor state, tenant partition details, and query filters. ### Identifying File Additions, Edits, and Deletions Every item returned in a delta query payload indicates a change. The payload distinguishes additions and modifications from deletions through specific facets: * **File Additions**: The item appears in the `value` array with standard properties (`name`, `size`, `file`, `lastModifiedDateTime`) that did not previously exist in the local store. * **File Updates**: The item ID matches an existing record in the local database, but `lastModifiedDateTime` or `eTag` values have advanced, signaling modified content. * **Deletions and Moves**: When a file or folder is removed from the document library or moved out of the monitored folder scope, Microsoft Graph returns the item ID accompanied by the `@removed` facet: ```json { "id": "01ABCDEF23456789", "@removed": { "reason": "deleted" } } ``` When an indexing pipeline encounters the `@removed` facet, it must delete the corresponding document embeddings and record metadata from its index. Failing to process tombstone records causes retrieval systems to hallucinate answers from files that no longer exist or leak references to unlinked documents. ### Implementing a Resilient Delta Query Poller The following TypeScript example demonstrates how to implement a stateful delta synchronization loop using the Microsoft Graph REST API. It handles nextLink iteration, updates local state, processes deletions, and stores the resulting deltaLink cursor: ```typescript interface DeltaItem { id: string; name?: string; size?: number; lastModifiedDateTime?: string; file?: { mimeType: string }; folder?: { childCount: number }; "@removed"?: { reason: string }; } interface DeltaResponse { "@odata.nextLink"?: string; "@odata.deltaLink"?: string; value: DeltaItem[]; } interface SyncStateStore { getDeltaLink(driveId: string): Promise; saveDeltaLink(driveId: string, link: string): Promise; upsertItem(driveId: string, item: DeltaItem): Promise; removeItem(driveId: string, itemId: string): Promise; } export async function syncSharePointDrive( driveId: string, accessToken: string, stateStore: SyncStateStore ): Promise<{ processed: number; newDeltaLink: string }> { const savedLink = await stateStore.getDeltaLink(driveId); let requestUrl = savedLink || `https://graph.microsoft.com/v1.0/drives/${driveId}/root/delta`; let processedCount = 0; let finalDeltaLink = ""; while (requestUrl) { const response = await fetch(requestUrl, { method: "GET", headers: { Authorization: `Bearer ${accessToken}`, Prefer: "hierarchicalsharing", }, }); if (response.status === 410) { throw new Error("DELTA_TOKEN_EXPIRED"); } if (!response.ok) { throw new Error(`Graph API error: ${response.status} ${response.statusText}`); } const data = (await response.json()) as DeltaResponse; for (const item of data.value) { if (item["@removed"]) { await stateStore.removeItem(driveId, item.id); } else { await stateStore.upsertItem(driveId, item); } processedCount++; } if (data["@odata.nextLink"]) { requestUrl = data["@odata.nextLink"]; } else if (data["@odata.deltaLink"]) { finalDeltaLink = data["@odata.deltaLink"]; await stateStore.saveDeltaLink(driveId, finalDeltaLink); break; } else { break; } } return { processed: processedCount, newDeltaLink: finalDeltaLink }; } ``` Notice the use of the `Prefer: hierarchicalsharing` header. In SharePoint document libraries with complex permission inheritance, this header reduces payload bloat by omitting redundant sharing facets unless an item breaks inheritance. ## Why SharePoint Delta Tokens Expire and How to Handle HTTP 410 Gone While Microsoft Graph delta queries significantly reduce sync overhead, production deployments frequently encounter edge cases where state tracking breaks down. The most critical edge case is `sharepoint delta token expiration`, which manifests as an HTTP 410 Gone status code. Microsoft Graph returns HTTP 410 Gone when delta tokens become stale, forcing a complete and costly re-enumeration of the document library. When this occurs, the server-side change log can no longer bridge the gap between the point in time captured in the client token and the current storage state. ### Root Causes of Delta Token Invalidation Delta tokens do not remain valid indefinitely. Four primary scenarios cause Microsoft Graph to reject an established delta link: 1. **Prolonged Polling Inactivity**: Microsoft Graph maintains internal change logs within a rolling cache. If a background synchronization service stops running, crashes, or is paused for an extended period, the server evicts older tokens from memory. 2. **Library Restorations from Backup**: If an administrator restores a SharePoint site collection or document library from a point-in-time backup, the internal object version history shifts backward. Stored delta tokens pointing to versions after the restore timestamp become invalid. 3. **Mass Deletions and Reorganizations**: Bulk operations that delete, move, or recreate tens of thousands of items can exhaust the server transaction log allocated for delta tracking, forcing an immediate sync reset. 4. **App Registration Permission Changes**: If the Azure app registration credentials lose delegated or application scopes, Microsoft Graph invalidates previous delta tokens to prevent security boundary bypasses. ### The HTTP 410 Gone Recovery Workflow When an application receives an HTTP 410 response from a delta endpoint, it must not treat the failure as a temporary network error. Retrying the same URL will consistently fail. Instead, the application must execute a full state resynchronization: ```http HTTP/1.1 410 Gone Content-Type: application/json Location: https://graph.microsoft.com/v1.0/drives/b!AbCdEf123/root/delta { "error": { "code": "resyncChangesApplyDifferences", "message": "The delta token is stale and invalid. Full synchronization is required." } } ``` When handling HTTP 410 Gone, follow these recovery procedures: * **Inspect the Location Header**: Microsoft Graph typically includes a `Location` header containing a clean delta URL without a state token. * **Evaluate the Error Code**: The two common error codes are `resyncChangesApplyDifferences` and `resyncChangesUploadDifferences`. For read-only indexing pipelines, both codes require dropping the invalid token and initiating a fresh baseline crawl. * **Purge Unmatched Local Cache**: During a resynchronization pass, items deleted in SharePoint while the sync service was offline will not appear in the baseline query. The indexing engine must reconcile its existing document catalog against the full baseline scan, purging local records that are absent from the server. * **Establish a New Baseline Cursor**: Follow `@odata.nextLink` pagination across the entire library until reaching the new `@odata.deltaLink`. Store the fresh token to resume normal incremental synchronization. ### Managing Microsoft Graph Rate Limits and Throttling A major gap in competitor guides is failing to address how high-volume SharePoint delta streams exhaust AI agent rate limits, omitting intermediate indexed workspace solutions. Microsoft Graph enforces multi-tiered throttling across tenants, applications, and individual user accounts. When a synchronization worker issues requests too rapidly, Graph responds with HTTP 429 Too Many Requests: ```http HTTP/1.1 429 Too Many Requests Retry-After: 35 Content-Type: application/json { "error": { "code": "activityLimitReached", "message": "Client application has exceeded request volume limit." } } ``` When building direct Graph polling into AI agent runtimes, this rate limiting creates severe operational friction. If an agent executes document retrievals, triggers embedding updates, and inspects file updates within the same process, a spike in SharePoint file edits can consume the entire tenant API quota. When Graph throttles the application, the agent stalls, unable to read or write any Microsoft 365 data until the `Retry-After` duration elapses. To mitigate throttling, client code must parse the `Retry-After` header, apply exponential backoff with jitter, and decouple high-frequency agent queries from low-level storage change tracking. ## Architecting AI Agent Indexing with Intermediate Workspaces Directly connecting AI agents to SharePoint document libraries creates an architectural mismatch. Autonomous agents need low-latency semantic search, dependable context retrieval, and simple tool interfaces. Conversely, Microsoft Graph requires complex token persistence, recursive nextLink paging, OAuth token refresh cycles, and defensive throttling backoff. Placing an intermediate indexed workspace between SharePoint and autonomous agents solves this challenge. Instead of forcing agents to act as cloud synchronization daemons, the storage infrastructure handles delta sync in the background while exposing clean retrieval endpoints to AI runtimes. ### Decoupling Synchronization from Agent Reasoning In an intermediate workspace architecture, enterprise teams keep their files in SharePoint, preserving their established folder structures, sharing policies, and daily workflows. A background connector mirrors document updates into an intelligent workspace, which indexes content for retrieval. Fast.io provides this intermediate coordination layer. Fastio syncs SharePoint libraries via the OneDrive connector on a schedule or on demand, insulating agents from Graph delta complexities. Cloud Sync connects Google Drive, Dropbox, Box and OneDrive folders to a workspace, one-way or two-way, on a schedule or on demand (never continuous, live or real-time; SharePoint libraries through the OneDrive connector). ``` +-------------------------------------------------------------------+ | Enterprise Storage: Microsoft SharePoint Document Libraries | +-------------------------------------------------------------------+ | | Scheduled / On-Demand Cloud Sync v +-------------------------------------------------------------------+ | Fast.io Workspace: Intermediate Coordination & Indexing Layer | | - Automatic Intelligence Mode (Hybrid Semantic + Full-Text Search)| | - Structured Metadata Views (/product/document-data-extraction/) | | - Per-File Version History & Detailed Activity Log | +-------------------------------------------------------------------+ | | Streamable HTTP (/mcp/tools, /mcp/code) v +-------------------------------------------------------------------+ | AI Agents & Runtimes: Claude, Cursor, Codex, OpenClaw, Gemini | | (Search, read, and reason without managing Graph API delta tokens)| +-------------------------------------------------------------------+ ``` When files arrive in a Fast.io workspace, Intelligence Mode automatically indexes documents for full-text search, semantic search, and metadata queries. Agents do not need to download multi-megabyte binary files, generate custom text chunks, or manage vector database embedding pipelines. The workspace performs indexing on arrival. ### Standardized Agent Access via the Model Context Protocol Autonomous agents access the workspace using the Model Context Protocol (MCP). Fast.io hosts a remote MCP server over Streamable HTTP with dedicated endpoints tailored to specific client categories: * **Claude Applications and General Agents**: `https://mcp.fast.io/mcp/tools` (Claude desktop, web, mobile, Cowork, OpenClaw, Hermes Agent) * **ChatGPT and Codex**: `https://mcp.fast.io/mcp/operations` (after installing the Fastio plugin from the ChatGPT plugin directory, or as a custom server) * **Coding Agents in IDEs and Terminals**: `https://mcp.fast.io/mcp/code` (Claude Code, Cursor, Gemini CLI, Cline, Roo Code, VS Code Copilot agent mode) Connecting an agent takes minimal configuration. For example, in Claude Code, adding the endpoint requires a single command: ```bash claude mcp add --transport http fast-io https://mcp.fast.io/mcp/code ``` Once connected, agents call a consolidated MCP toolset (`storage`, `storage_manage`, `search`, `execute`). Instead of downloading raw document streams from SharePoint and burning context tokens, the agent issues semantic queries against the indexed workspace. The search tool returns precise, citation-backed document excerpts, preserving context window capacity for complex reasoning. This architecture delivers dramatic performance advantages. In Claude Cowork benchmarks comparing native cloud storage connectors, Fastio was measured the fastest and the lowest cost of the providers tested. The full methodology and results are published at [Fast.io Benchmarks](https://fast.io/benchmarks/). For related background on Microsoft Graph delta mechanics in OneDrive environments, see the detailed breakdown in [OneDrive Delta Sync](https://fast.io/resources/onedrive-delta-sync/). ## Key Steps for Resilient SharePoint Change Tracking in AI Systems Building production-grade `sharepoint change tracking for ai` requires accounting for enterprise storage realities: large file payloads, complex metadata, version collisions, and team collaboration patterns. Applying proven engineering patterns ensures your indexing pipelines remain reliable. ### 1. Build Idempotent Ingestion Pipelines Delta query streams guarantee that every change will be delivered at least once, but replays are common. Microsoft Graph occasionally resends identical items across subsequent deltaLink calls if internal cluster nodes reconcile state. Indexing pipelines must be strictly idempotent: * Check file revision indicators (`eTag`, `cTag`, or `lastModifiedDateTime`) before triggering expensive re-chunking or re-embedding workflows. * If a delta record carries an identical modification timestamp to the existing index entry, acknowledge the item without reprocessing. * Treat deletions as idempotent: deleting a non-existent index record should succeed silently. ### 2. Scope Tracking to Specific Subfolder Hierarchies Querying delta changes at the root of a large SharePoint document library can produce massive change volumes, especially in organizations where thousands of automated reports or telemetry logs are dumped daily into unrelated folders. To prevent agent indexing queues from clogging: * Scope queries to specific operational folders using `GET /drives/{drive-id}/items/{folder-id}/delta`. * Segregate dynamic scratch directories from reference document folders in SharePoint. * By isolating high-value knowledge repositories, your synchronization workers process fewer irrelevant mutations and stay well beneath Microsoft Graph rate limits. ### 3. Extract Structured Information with Metadata Views Unstructured semantic search is effective for question answering, but agent workflows often require structured document attributes such as contract renewal dates, counterparty names, policy numbers, or line-item totals. Rather than running separate optical character recognition scripts and regular expression extractors, use [Metadata Views](/product/document-data-extraction/) within Fast.io workspaces. Metadata Views allow teams and agents to describe target fields in plain English. The platform designs typed schemas (Text, Integer, Decimal, Boolean, URL, JSON, Date & Time), extracts values directly from incoming documents, and populates filterable, queryable tables. Agents query structured document metadata alongside semantic file content through MCP tools. ### 4. Maintain Auditability with Version History and Activity Logging When multiple agents and human team members collaborate around enterprise files, tracking who changed what is essential for security and accountability: * **Per-File Version History**: Fast.io preserves every file revision automatically. If an agent updates a project document or a user modifies a specification, prior versions remain accessible and auditable. * **Detailed Activity Log**: A detailed activity log records all storage changes across the workspace, including uploads, edits, moves, deletions, and permission changes. It tracks what changed and who changed it, giving engineering teams visibility into file lifecycle events without logging noisy read-only views or downloads. * **Workspace Permissions**: Access permissions are configured per organization, workspace, and share using member roles. This eliminates confusing folder-level permission sprawl while ensuring agents operate within clearly defined organizational boundaries. ### 5. Transitioning from Direct Polling to Managed Synchronization Teams scaling AI agent deployments should evaluate the engineering cost of maintaining custom Microsoft Graph delta polling engines against managed intermediate workspaces: * **Custom Graph Poller**: Requires maintaining persistent token databases, custom 410 Gone recovery logic, 429 rate limit backoff handlers, OAuth token rotation, local embedding chunkers, and vector database infrastructure. * **Managed Workspace Architecture**: Keeps SharePoint as the system of record, uses scheduled Cloud Sync to mirror libraries, auto-indexes content on arrival, and exposes a remote MCP server for instant agent integration. Monthly plans for Fast.io workspaces start with a 14-day free trial, which requires a credit card. Plans are Starter at `$9.99/mo`, Business at `$49.99/mo`, and Enterprise at `$199.99/mo`. Storage allowances include `250 GB` on Starter, `5 TB` on Business, and `25 TB` on Enterprise, with maximum upload limits of `25 GB`, `50 GB`, and `100 GB` respectively. Usage credits meter AI operations, allowing engineering teams to scale agent context cost-effectively. ## Frequently asked questions ### How do Microsoft Graph delta queries work on SharePoint document libraries? Microsoft Graph delta queries track changes to files and folders in a SharePoint document library using a stateful cursor pattern. An initial GET request to the driveItem delta endpoint returns pages of current items followed by an @odata.deltaLink containing a state token. When an application calls this deltaLink URL on subsequent synchronization cycles, Microsoft Graph returns only the files that were added, modified, or deleted since the token was created. ### What causes a SharePoint delta token to expire? SharePoint delta tokens expire when synchronization loops remain inactive for extended periods, causing Microsoft Graph internal cache eviction. Tokens also become invalid when site collections are restored from backups, when large-scale file reorganizations or bulk deletions exhaust server transaction logs, or when app registration permissions are modified. In these cases, Microsoft Graph returns an HTTP 410 Gone response requiring a full baseline resynchronization. ### How can AI tools stay synchronized with SharePoint changes efficiently? AI tools synchronize most efficiently by using an intermediate workspace layer rather than polling Microsoft Graph directly. By syncing SharePoint document libraries into a Fast.io workspace on a schedule or on demand via Cloud Sync, documents are automatically indexed for full-text and semantic search. AI agents then query the indexed content through the remote Fast.io MCP server, eliminating the need to manage Graph API pagination, rate limits, or delta tokens. ### What is the difference between @odata.nextLink and @odata.deltaLink? @odata.nextLink is a transient pagination URL containing a skipToken used to fetch the next page of results within an ongoing synchronization batch. In contrast, @odata.deltaLink is returned only on the final page of a batch and contains a deltaToken representing a completed point-in-time synchronization marker. Applications must persist @odata.deltaLink to retrieve future incremental changes. ### Does using an intermediate workspace require migrating away from SharePoint? No. Teams continue using SharePoint as their primary document management system. Fast.io Cloud Sync connects SharePoint document libraries through the OneDrive connector on a schedule or on demand, copying files into a dedicated workspace. This enables autonomous agents to search and access versioned files without modifying existing enterprise SharePoint architectures or permissions. ## Sources - [Microsoft Graph Documentation: driveItem: delta](https://learn.microsoft.com/en-us/graph/api/driveitem-delta?view=graph-rest-1.0): Microsoft Graph delta queries track incremental changes in a drive hierarchy over time, returning an @odata.deltaLink on the final page to retrieve subsequent changes. ## About Fast.io Fast.io provides shared workspaces where people and AI agents work on the same files, with built-in semantic search and citation-backed chat over what they hold. Agents reach it through a remote MCP server, a REST API at https://api.fast.io/current/, and a command line client published on npm as @vividengine/fastio-cli. MCP setup is at https://mcp.fast.io/docs: Claude and most MCP clients connect to https://mcp.fast.io/mcp/tools, ChatGPT to https://mcp.fast.io/mcp/operations, and coding agents to https://mcp.fast.io/mcp/code.