# Box Delta Sync: Events API, Polling Patterns, and Agent Indexing Box delta sync uses the Box Events API and stream position markers to track file additions, updates, and deletions across enterprise repositories. By replacing recursive folder scans with cursor-based change streams and long polling, synchronization engines capture repository updates without exhausting API rate limits. Intermediate workspaces then index synchronized Box documents for AI agents to query without continuous polling overhead. Source: https://fast.io/resources/box-delta-sync/ Author: [Tom Langridge](https://fast.io/authors/tom-langridge/) Last reviewed: 2026-11-08 ## How Box Delta Sync Solves Enterprise Repository Tracking Enterprise repositories in Box change continuously as product, engineering, and legal teams upload documents, revise project files, and restructure shared folders. Pointing an autonomous AI agent or background synchronization service directly at an enterprise Box repository and traversing nested folders recursively rapidly degrades performance, consumes API quotas, and triggers rate limits. Box delta sync is an incremental synchronization method that tracks changes in a Box enterprise repository using event streams and stream position markers, transferring only modified files. Box delta sync monitors repository modifications by querying Box event streams rather than walking static directory trees. An application establishes an initial stream position marker and receives sequential change events for file uploads, updates, and deletions. By maintaining this cursor, synchronization engines ingest only altered documents into target workspaces without rescanning unchanged folders. ### The Breakdown of Recursive Folder Traversal When applications attempt to track changes by querying standard folder endpoints like `GET /folders/{folder_id}/items`, they encounter severe scaling limits. In a typical corporate Box deployment containing tens of thousands of files across deep directory hierarchies, checking for updates requires traversing every subfolder branch. This recursive crawling pattern introduces several operational bottlenecks: * **High Request Volumes**: Discovering a single modified file in a deeply nested subfolder requires issuing an API call for every ancestor and sibling folder across the directory tree. * **Severe Rate Limit Vulnerability**: Enterprise Box accounts enforce per-user and per-minute request thresholds. Recursive directory walks quickly consume these quotas, leading to HTTP 429 rate limit errors. * **High Latency for Fresh Context**: By the time a full folder traversal finishes querying thousands of folders, hours have passed. The synchronization engine operates on stale representations of repository state. * **Invisible Deletions**: Detecting that a user deleted a file during a folder crawl requires calculating an expensive full-state diff against a local database inventory. ### Recursive Directory Crawling vs. Stream-Based Delta Sync Comparing traditional folder crawling with event-driven delta sync illustrates why cursor-based tracking is necessary for production agent architectures: | Synchronization Dimension | Recursive Folder Crawl (`/folders/{id}/items`) | Stream-Based Delta Sync (`/events`) | |---|---|---| | Query Target | Present directory snapshot | Unified chronological change log | | Baseline Discovery | One API call per folder in tree | Sequential paged requests over event feed | | Ongoing Discovery Cost | Hundreds of repeated folder inspections | Single request returning recent change events | | Deletion Detection | Full inventory diff against local cache | Explicit delete event entries (`ITEM_TRASH`) | | Rate Limit Exposure | High risk of HTTP 429 throttling | Minimal request footprint during sync runs | | Agent Retrieval Readiness | Delayed until full directory walk finishes | Fast incremental ingestion | Instead of querying the state of every folder container, Box delta sync flattens change tracking into an append-only event stream. Synchronization engines record an opaque stream position marker and consume only the events that occurred after that point in time. ## How the Box Events API Tracks Changes with Stream Position Markers The Box Events API (`GET https://api.box.com/2.0/events`) acts as the foundation for Box delta sync. The endpoint provides a structured, chronological record of actions occurring within an account, allowing external tools to track updates without inspecting individual file objects. ### Stream Types and Feed Scopes The Box Events API supports different stream types tailored to specific synchronization requirements: * **User Events (`all`)**: Returns events relevant to the authenticated user, covering file uploads, content modifications, moves, copies, and deletions across all folders the user can access. * **User Changes (`changes`)**: Returns a streamlined subset of user events specifically focused on file and folder data changes, filtering out ancillary collaboration notifications. * **User Sync (`sync`)**: Optimized specifically for desktop file synchronization engines like Box Drive, delivering fast notifications of file additions and deletions. * **Enterprise Admin Logs (`admin_logs` and `admin_logs_streaming`)**: Exposes enterprise-wide events across all managed users. These streams require administrative permissions and are designed for compliance auditing and security analysis rather than targeted folder synchronization. User events provide a low latency stream of events relevant to the currently authenticated user, which is how Box keeps Box Drive up to date. This user event stream serves as the primary mechanism for delta synchronization workflows. ### Managing Stream Position Markers The core concept in Box delta sync is the `stream_position` parameter. The stream position acts as a persistent cursor that tracks how far a client has progressed through the event stream. The stream position lifecycle follows a structured sequence: 1. **Initial Baseline Query**: To read events from the beginning of the available retention window, an application calls `GET /events` without providing a `stream_position` parameter. The response returns the oldest available batch of events alongside a `next_stream_position` field. 2. **Current Point-in-Time Anchor (`stream_position=now`)**: When a synchronization engine already possesses a baseline file inventory or wishes to ignore historical events, it calls `GET /events?stream_position=now`. Box returns an empty list of event entries and provides the current `next_stream_position` marker. This anchors the engine to receive only future events. 3. **Persisting the Cursor**: The application stores the received `next_stream_position` string in durable local storage, such as a transactional database or state cache. 4. **Incremental Fetching**: During subsequent synchronization cycles, the application passes the stored cursor into the request: `GET /events?stream_position={stored_cursor}`. Box evaluates the marker and returns only the events generated after that cursor was established. 5. **Cursor Advancement**: Upon successfully processing the returned events, the application updates its stored cursor to the new `next_stream_position` returned in the response header or body. ```bash curl -X GET "https://api.box.com/2.0/events?stream_position=1152921504606846975&stream_type=changes&limit=100" -H "Authorization: Bearer ACCESS_TOKEN" ``` ### Event Payload Structure and Deduplication A response from `GET /events` contains a JSON collection of event objects: ```json { "chunk_size": 2, "next_stream_position": "1152921504606847120", "entries": [ { "type": "event", "event_id": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6", "created_at": "2026-11-08T09:15:30Z", "event_type": "ITEM_UPLOAD", "source": { "type": "file", "id": "184920491823", "name": "quarterly_earnings_report.pdf", "parent": { "type": "folder", "id": "84729104812", "name": "Financial Documents" } } }, { "type": "event", "event_id": "a3b2c1d0-8e1f-22e1-b876-11b1d02f7ca8", "created_at": "2026-11-08T09:16:05Z", "event_type": "ITEM_TRASH", "source": { "type": "file", "id": "184920491100", "name": "draft_briefing_notes.docx" } } ] } ``` Key event types relevant to delta sync include: * **`ITEM_UPLOAD` and `ITEM_CREATE`**: Indicate that a new file was added to a folder. The client extracts the file ID and schedules a download or indexing task. * **`ITEM_MODIFY`**: Indicates that an existing file was edited or replaced with a new version. * **`ITEM_RENAME`**: Signals that a file or folder was renamed without changing its ID. * **`ITEM_MOVE`**: Indicates that an item was moved to a new parent folder. * **`ITEM_TRASH`**: Explicitly communicates that an item was moved to the trash, allowing the local sync target to remove or archive the file immediately. Because the user events feed prioritizes rapid delivery over strict chronological sequencing, Box may occasionally emit duplicate event objects or deliver them slightly out of order. Synchronization engines handle this behavior by tracking recent `event_id` values in a local deduplication cache. ## Comparing Long Polling and Periodic Polling for Change Detection Applications integrating with Box delta sync choose between two primary operational patterns to retrieve updates: long polling over a dedicated socket or periodic scheduled polling. ### How Box Real-Time Long Polling Operates Rather than making repeated HTTP GET requests to `GET /events` at fixed intervals, applications can subscribe to Box real-time notifications via HTTP long polling. Long polling uses a two-phase connection workflow: 1. **Discovering the Real-Time Server**: The client issues an `OPTIONS` request to the events endpoint: ```bash curl -X OPTIONS "https://api.box.com/2.0/events" -H "Authorization: Bearer ACCESS_TOKEN" ``` 2. **Parsing Connection Parameters**: Box returns connection metadata pointing to a dedicated real-time server: ```json { "chunk_size": 1, "entries": [ { "type": "realtime_server", "url": "https://2.realtime.services.box.net/subscribe?channel=ab12cd34ef56&stream_type=all", "ttl": 10, "max_retries": 10, "retry_timeout": 610 } ] } ``` 3. **Holding the Long-Poll Connection**: The client makes an HTTP GET request to the provided `url`. The Box real-time server holds this connection open until a new event occurs or the `retry_timeout` period expires. 4. **Triggering Event Ingestion**: When an action occurs in the user repository, the real-time server responds immediately with a notification payload: ```json { "message": "new_change" } ``` 5. **Fetching Event Details**: Upon receiving the `new_change` notification, the application issues a standard `GET /events?stream_position={stored_cursor}` call to fetch the concrete change records, updates its cursor, and re-establishes the long-poll connection. ### Tradeoffs Between Long Polling and Scheduled Polling While long polling provides near-instantaneous notification of repository modifications, it requires keeping a persistent background worker process and managing network socket reconnects. If network partitions occur, the process must re-negotiate connection URLs via `OPTIONS /events`. Periodic scheduled polling, in contrast, executes at predefined intervals (such as every fifteen minutes or every hour). The scheduled worker queries `GET /events?stream_position={stored_cursor}`, processes the batch of change records, updates the stored cursor, and terminates. This approach avoids persistent daemon management and fits cleanly into containerized batch architectures. ### Box API Rate Limits and Error Handling Whether using long polling or periodic intervals, synchronization services must operate within Box API rate limits. Box enforces strict request boundaries to protect infrastructure stability: * **User Request Caps**: Box limits general API calls to approximately 1,000 requests per minute per user account. * **Upload Boundaries**: File upload endpoints carry separate restrictions, capped at 240 requests per minute per user. * **Dynamic Infrastructure Throttling**: Box monitors underlying database resource contention. If multiple bulk migration processes access shared physical storage clusters concurrently, Box imposes temporary dynamic throttling. When an application hits a rate limit, the API will return an API response with an HTTP status code of 429 Too Many Requests. The HTTP 429 response includes a `Retry-After` header indicating how many seconds the application must wait before retrying the call: ```http HTTP/1.1 429 Too Many Requests Date: Sun, 08 Nov 2026 10:20:00 GMT Content-Type: application/json Retry-After: 35 { "type": "error", "status": 429, "code": "rate_limit_exceeded", "message": "Request rate limit exceeded, please try again later" } ``` Reliable delta synchronization scripts must inspect the `Retry-After` header, apply exponential backoff with jitter, and avoid tight retry loops that compound platform throttling. ## Why AI Agents Need Intermediate Workspaces for Box Content Autonomous AI agents and language models encounter severe friction when interacting directly with enterprise cloud storage. When an agent in Claude Code, Cursor, ChatGPT, or Claude Cowork needs to consult business documents stored in Box, querying raw storage APIs directly is slow and inefficient. ### The Problem with Direct Storage Access for Language Models Developers frequently attempt to connect AI agents directly to Box by giving them API credentials and tools to search and download files on demand. In practice, this direct access model fails across three main dimensions: 1. **Context Window Saturation**: Passing raw directory hierarchies, JSON file metadata, and unparsed document text directly into an LLM prompt burns thousands of context tokens before the agent can begin answering the user prompt. 2. **Repetitive Tool Calls**: An agent attempting to locate specific information in nested Box folders must make sequential tool calls to list folders, check file names, and download document contents. Each round trip introduces network latency and increases token consumption. 3. **Rate Limit Exposure**: If multiple agents or complex multi-step reasoning workflows query Box simultaneously, they quickly breach the per-minute request limit, triggering HTTP 429 errors that abort agent runs. The connector comparison is published at [https://fast.io/benchmarks/](https://fast.io/benchmarks/) and that page is the only place its numbers live. In that published report, Fastio was measured the fastest and the lowest cost of the providers tested. ### The Intermediate Workspace Pattern Rather than forcing AI agents to manage Box API authentication, cursor pagination, and file downloads directly, teams use an intermediate workspace architecture. In this pattern: * **Box Remains the Enterprise System of Record**: Human teams continue working in Box, maintaining established enterprise access controls and directory conventions. Teams exploring alternatives can review our [guide to Box alternatives](/alternatives/box/). * **Workspaces Mirror Target Folders**: Designated Box folders sync into [Fastio workspaces](/product/workspaces/) using Cloud Sync. Cloud Sync connects Google Drive, Dropbox, Box and OneDrive folders to a workspace, one-way or two-way, on a schedule or on demand. * **Automatic Workspace Indexing**: Once files arrive in the workspace, Fastio Intelligence Mode automatically indexes documents for hybrid search, combining full-text keyword retrieval, semantic understanding, and metadata matching. * **Remote MCP Server Access**: Autonomous agents connect to the workspace through the hosted Model Context Protocol (MCP) server. Instead of downloading whole files or parsing directory trees, the agent executes targeted semantic searches that return relevant text excerpts alongside verified file citations. Learn more about configuring [storage for AI agents](/storage-for-agents/). ## Steps to Connect Box Delta Sync to Managed Fastio Workspaces Engineering teams evaluating how to support autonomous agents on top of Box data face a fundamental choice: build and maintain custom delta sync infrastructure, or connect Box to managed intermediate workspaces. ### The Engineering Overhead of Custom Delta Sync Pipelines Building a custom synchronization service on top of the Box Events API requires significant ongoing engineering overhead: * Maintaining persistent state databases to track `stream_position` cursors across crashes and restarts. * Implementing long-poll reconnect daemons and HTTP 429 exponential backoff retry algorithms. * Parsing multi-format document payloads (PDFs, spreadsheets, presentations, and scans) into clean text chunks. * Operating vector databases, embedding generation pipelines, and hybrid search indexes. * Managing OAuth token refreshing, webhook validation, and enterprise rate limit budgets. ### Managed Intermediate Workspaces with Fastio Fastio decouples enterprise file repositories from agent consumption layers, providing an intelligent workspace that handles synchronization, indexing, and agent access automatically. Key capabilities supporting agentic teams include: * **Scheduled Cloud Sync**: Mirror specific Box folders into Fastio workspaces on a schedule or on demand, keeping agent context current without continuous manual exports. * **Consolidated MCP Toolset**: Connect AI agents over Streamable HTTP at `https://mcp.fast.io/mcp/tools` (for Claude apps and general agents) or `https://mcp.fast.io/mcp/code` (for coding agents). Agents query workspace files using natural language search actions rather than custom REST scripts. Setup guides and connection steps are documented at [https://mcp.fast.io/docs](https://mcp.fast.io/docs). * **Per-File Version History**: Every document modification maintains a complete version record, allowing teams to audit agent changes, track revisions, and restore previous states when necessary. * **Role-Based Permissions**: Access controls are configured per organization, workspace, and share using member roles. This provides clean boundaries without complex folder-level permission sprawl. * **Advisory File Leases**: Multi-agent pipelines coordinate updates using advisory leases via `lock-acquire` and `lock-release` on `storage_manage` and `lock-status` on `storage`. Concurrent writes land safely while preserving version history. * **Metadata Views**: Extract structured data from unstructured contracts, invoices, and forms into sortable, filterable schemas using [Metadata Views](/product/document-data-extraction/). Monthly plans start with a 14-day free trial, which requires a credit card. Plans are Starter at `$9.99/mo` (3 seats, `250 GB` storage, 5 workspaces, `100,000 credits` a month), Business at `$49.99/mo` (10 seats, `5 TB` storage, 50 workspaces, `600,000 credits` a month), and Enterprise at `$199.99/mo` (30 seats included, `25 TB` storage, 200 workspaces, `3,000,000 credits` a month). Maximum upload sizes are `25 GB` on Starter, `50 GB` on Business, and `100 GB` on Enterprise. Credits meter AI work. Storage and seats come with the plan. Complete subscription tiers are available on the [Fastio pricing page](/pricing/). ## Frequently asked questions ### How does Box delta sync work? Box delta sync tracks modifications across an enterprise repository using the Box Events API and stream position markers. An application queries the events endpoint with an initial cursor, receives a batch of change events detailing file uploads, edits, and deletions, and updates its local stream position marker. Subsequent requests query only the changes generated after that marker, eliminating recursive folder scans. ### What is the Box Events API stream position? The stream position is an opaque string marker that indicates an application point of progress within the Box event feed. Passing a stream position to the events endpoint returns only events that occurred after that point. The API returns a next_stream_position value in each response, which the application stores to query future incremental changes. ### How can AI agents sync files from Box without hitting rate limits? AI agents avoid Box rate limits by using an intermediate workspace layer rather than polling Box APIs directly. By syncing Box folders into Fastio workspaces on a schedule or on demand via Cloud Sync, files are automatically indexed for full-text and semantic search. Agents then query documents through the remote MCP server, avoiding repetitive Box API calls. ### What is the difference between user events and enterprise admin logs in Box? User event streams track low-latency actions performed on files and folders accessible to a specific authenticated user, supporting rapid delta synchronization and long polling. Enterprise admin logs cover actions across all users in the enterprise, require administrative privileges, and are designed for security auditing rather than real-time file synchronization. ### How does long polling differ from periodic scheduled polling in Box? Long polling opens an HTTP GET connection to a dedicated real-time server discovered via an OPTIONS request, holding the connection open until Box emits a change notification. Periodic scheduled polling instead queries the events endpoint at fixed time intervals using a saved stream position marker, which avoids running a continuous background daemon. ### Does connecting an intermediate workspace require migrating files away from Box? No. Enterprise teams continue using Box as their primary system of record. Fastio Cloud Sync connects Box folders to a dedicated workspace on a schedule or on demand, copying files into intermediate storage where AI agents search indexed content without altering existing Box folder structures or enterprise permissions. ## Sources - [Box Developer Documentation: Events](https://developer.box.com/guides/events/): User events provide a low latency stream of events relevant to the currently authenticated user, which is how Box keeps Box Drive up to date. - [Box Developer Documentation: Box API rate limits](https://developer.box.com/guides/api-calls/permissions-and-errors/rate-limits/): When an application hits a rate limit, the API will return an API response with an HTTP status code of 429 Too Many Requests. ## 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.