How to List Files with SharePoint API: REST, Graph, and Agent Workspaces

Directing an autonomous agent to crawl a SharePoint document library to list files recursively causes immediate API rate limits and burns context windows before the model inspects a single document. Each nested folder requires a separate round trip through server-relative paths or drive item hierarchies, and large enterprise libraries trigger pagination loops that flood the agent with repetitive OData payloads. The architectural alternative is syncing the target SharePoint document library into a Fast.io workspace, where files are automatically indexed for hybrid search and queried directly over the Model Context Protocol without crawling directory trees.

Listing files with the SharePoint API involves querying the SharePoint REST endpoint or Microsoft Graph drive items to enumerate documents in a target library.

Engineering teams integrating SharePoint file storage encounter two distinct API surfaces. Microsoft Graph serves as the unified API gateway across Microsoft 365 services, treating SharePoint document libraries as drives and files as drive items. In contrast, the classic SharePoint REST API (/_api/web/) interacts directly with SharePoint site objects, treating document libraries as lists and files as items within server-relative folder structures. For teams evaluating storage integrations for autonomous systems, Fast.io storage for agents provides dedicated workspace endpoints designed specifically for structured model access.

Side-by-Side Endpoints and Request Headers

The two API architectures require different endpoint URLs, path conventions, and request headers:

// SharePoint REST API: List files in a specific folder by server-relative URL
GET https://{tenant}.sharepoint.com/sites/{site}/_api/web/GetFolderByServerRelativeUrl('{server-relative-path}')/Files
Authorization: Bearer {token}
Accept: application/json;odata=verbose

// Microsoft Graph API: List child drive items in a document library folder
GET https://graph.microsoft.com/v1.0/sites/{site-id}/drives/{drive-id}/items/{folder-id}/children
Authorization: Bearer {token}
Accept: application/json

The SharePoint REST API uses verbose OData formatting by default, requiring client applications to parse nested d.results payloads. Microsoft Graph returns standardized JSON objects containing a flat value array, standardizing metadata properties across personal OneDrive storage and enterprise SharePoint sites.

Architectural Comparison

Choosing between Microsoft Graph and the SharePoint REST API determines authentication scopes, addressing semantics, and traversal mechanics:

While Microsoft Graph is the recommended path for modern cloud integrations, understanding both interfaces is essential when working with legacy enterprise libraries, custom metadata columns, or high-volume document archives.

• How to Create Folders with SharePoint API: REST, Graph, and Agent WorkspacesCreating folders across SharePoint environments requires choosing between legacy REST endpoints and modern Microsoft...
• How to List Files with OneDrive API: Graph Endpoints and Agent WorkspacesThe OneDrive API, integrated into Microsoft Graph, lists drive items using the /me/drive/root/children or...
• How to Download Files via OneDrive API: Microsoft Graph GuideDownloading a file via the OneDrive API requires requesting the binary stream from a driveItem content endpoint using...
• How to List Files with the Dropbox API: Pagination, Cursors, and Agent WorkspacesListing files through the Dropbox API requires managing cursor-based pagination across the /files/list_folder and...
• How to Download Files from Box via API: Endpoints, Tokens & LimitsDownloading files through the Box REST API requires requesting the GET /files/{file_id}/content endpoint and following...
• ChatGPT SharePoint Connector: Enterprise Setup vs. Fast.io MCP WorkspacesConnecting ChatGPT to SharePoint document libraries gives conversational models access to enterprise knowledge. While...

More on this subject: Agent File and Document Workflows (269 guides)

The classic SharePoint REST API interacts with the site collection web object (SP.Web) and exposes files through folder objects. When building integrations against classic SharePoint Online sites or on-premises SharePoint Server deployments, developers use the GetFolderByServerRelativeUrl method to target specific directories.

Server-Relative Pathing and URL Encoding

SharePoint REST API requires URL encoding and nested server-relative pathing. A server-relative URL begins with the site collection path rather than the fully qualified domain name. For example, if a site collection is hosted at https://tenant.sharepoint.com/sites/Engineering, the default document library path is /sites/Engineering/Shared Documents.

When passing this path into the REST endpoint, you must properly URL-encode special characters. Spaces become %20, single quotes within directory names must be escaped by doubling them (''), and slashes separate the hierarchical folder structure. A malformed server-relative path returns HTTP 404 (Item does not exist) or HTTP 400 (Bad Request).

Step 1: Query Files in a Folder Using GetFolderByServerRelativeUrl

To retrieve files residing in a specific folder, send an HTTP GET request to the /Files navigation property of that folder:

curl -X GET "https://example.sharepoint.com/sites/Engineering/_api/web/GetFolderByServerRelativeUrl('/sites/Engineering/Shared%20Documents/ProjectAlpha')/Files" \
  -H "Authorization: Bearer your-access-token" \
  -H "Accept: application/json;odata=verbose"

The response returns a verbose OData payload containing an array of file objects under d.results:

{
  "d": {
    "results": [
      {
        "__metadata": {
          "id": "https://example.sharepoint.com/sites/Engineering/_api/Web/GetFileByServerRelativeUrl('/sites/Engineering/Shared%20Documents/ProjectAlpha/architecture.pdf')",
          "uri": "https://example.sharepoint.com/sites/Engineering/_api/Web/GetFileByServerRelativeUrl('/sites/Engineering/Shared%20Documents/ProjectAlpha/architecture.pdf')",
          "type": "SP.File"
        },
        "CheckInComment": "",
        "CheckOutType": 2,
        "Length": "1048576",
        "Name": "architecture.pdf",
        "ServerRelativeUrl": "/sites/Engineering/Shared Documents/ProjectAlpha/architecture.pdf",
        "TimeCreated": "2026-09-12T14:32:00Z",
        "TimeLastModified": "2026-10-01T09:15:22Z",
        "UniqueId": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d"
      }
    ]
  }
}

Each file entry provides essential filesystem metadata, including Name, file size in bytes (Length), timestamp of last modification (TimeLastModified), and the unique GUID (UniqueId).

Step 2: Query All Documents in a Library via the Lists Endpoint

Because SharePoint document libraries are internally implemented as specialized lists, you can also enumerate documents using the lists API. This technique allows you to retrieve custom list column values attached to files:

GET https://example.sharepoint.com/sites/Engineering/_api/web/lists/getbytitle('Documents')/items?$select=FileLeafRef,FileRef,FSObjType,File/Length,File/TimeLastModified&$expand=File
Authorization: Bearer your-access-token
Accept: application/json;odata=verbose

In this query, FileLeafRef represents the file name, FileRef represents the server-relative path, and FSObjType indicates the item type. An FSObjType value of 0 corresponds to a file, while a value of 1 corresponds to a folder. Expanding the File object brings in physical file attributes such as byte length and modification timestamps.

POST https://example.sharepoint.com/sites/Engineering/_api/web/lists/getbytitle('Documents')/GetItems
Authorization: Bearer your-access-token
Content-Type: application/json;odata=verbose
Accept: application/json;odata=verbose

{
  "query": {
    "__metadata": { "type": "SP.CamlQuery" },
    "ViewXml": "<View Scope='RecursiveAll'><Query><Where><Eq><FieldRef Name='FSObjType' /><Value Type='Integer'>0</Value></Eq></Where></Query></View>"
  }
}

Microsoft Graph standardizes SharePoint file listing by modeling document libraries as drives and folders as drive items. Applications interact with clean JSON endpoints, consistent OAuth 2.0 permission scopes, and structured pagination.

Step 1: Discover Site ID and Drive ID

Before querying files in Microsoft Graph, your application must obtain the unique identifiers for the SharePoint site and document library.

First, look up the site by its hostname and site-relative path:

GET https://graph.microsoft.com/v1.0/sites/example.sharepoint.com:/sites/Engineering
Authorization: Bearer your-access-token
Accept: application/json

The response returns a composite site identifier formatted as example.sharepoint.com,{spsite-guid},{spweb-guid}. Using this site ID, query the site's document libraries:

GET https://graph.microsoft.com/v1.0/sites/example.sharepoint.com,{spsite-guid},{spweb-guid}/drives
Authorization: Bearer your-access-token
Accept: application/json

Identify the target document library (such as the default Documents library) and extract its id string.

Step 2: Query Drive Items in Root and Child Folders

With the drive ID in hand, you can list items in the root folder of the document library:

curl -X GET "https://graph.microsoft.com/v1.0/drives/{drive-id}/root/children" \
  -H "Authorization: Bearer your-access-token" \
  -H "Accept: application/json"

To list items within a specific subfolder, target that folder's unique drive item ID:

GET https://graph.microsoft.com/v1.0/drives/{drive-id}/items/{folder-item-id}/children
Authorization: Bearer your-access-token
Accept: application/json

Alternatively, you can query folders by path using colon delimiters:

GET https://graph.microsoft.com/v1.0/drives/{drive-id}/root:/ProjectAlpha/Specs:/children
Authorization: Bearer your-access-token
Accept: application/json

The response returns a JSON object containing an array of driveItem resources:

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#drives('b!1234')/items('01ROOT')/children",
  "value": [
    {
      "id": "01ABCDEXYZ111111",
      "name": "Design-Brief.docx",
      "size": 524288,
      "webUrl": "https://example.sharepoint.com/sites/Engineering/Shared%20Documents/Design-Brief.docx",
      "lastModifiedDateTime": "2026-09-28T11:20:15Z",
      "file": {
        "mimeType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
      }
    },
    {
      "id": "01ABCDEXYZ222222",
      "name": "Architecture-Diagrams",
      "size": 2097152,
      "webUrl": "https://example.sharepoint.com/sites/Engineering/Shared%20Documents/Architecture-Diagrams",
      "lastModifiedDateTime": "2026-10-02T16:45:00Z",
      "folder": {
        "childCount": 8
      }
    }
  ]
}

To differentiate files from subdirectories in your code, check for the presence of the folder facet. Objects containing a file facet represent documents, while objects containing a folder facet represent directories.

GET https://graph.microsoft.com/v1.0/drives/{drive-id}/root/children?$top=100&$select=id,name,size,file,folder,lastModifiedDateTime
Authorization: Bearer your-access-token
Accept: application/json

import requests

def list_all_drive_items(drive_id, access_token):
    url = f"https://graph.microsoft.com/v1.0/drives/{drive_id}/root/children?$top=100"
    headers = {"Authorization": f"Bearer {access_token}", "Accept": "application/json"}
    items = []
    while url:
        response = requests.get(url, headers=headers)
        response.raise_for_status()
        data = response.json()
        items.extend(data.get("value", []))
        url = data.get("@odata.nextLink")
    return items

Connect SharePoint Document Libraries to Agent Workspaces

Sync existing SharePoint libraries into Fast.io workspaces where AI agents search indexed files over MCP instead of traversing raw APIs. Monthly plans start with a 30-day free trial.

Start 30-Day Trial

While programmatic file enumeration functions reliably in scheduled batch scripts, deploying autonomous AI agents to crawl raw SharePoint directories introduces operational friction. Autonomous agents typically require document context to solve specific user inquiries. Forcing an agent to crawl directory trees using direct REST or Microsoft Graph calls leads to three compounding failures: API throttling, context window exhaustion, and latency compounding.

HTTP 429 Throttling and Resource Consumption

SharePoint Online and Microsoft Graph enforce strict rate limits to protect multi-tenant infrastructure. When an application issues rapid sequential calls to traverse directories, SharePoint flags the pattern as excessive resource consumption and responds with HTTP 429 (Too Many Requests).

The response includes a Retry-After header indicating the number of seconds the application must pause before retrying. SharePoint throttling algorithms monitor CPU usage, database worker threads, and concurrent request volume per tenant. Because autonomous agents frequently execute multiple tool calls in rapid succession, directory-crawling loops routinely trigger throttling, pausing agent execution for extended intervals.

Context Window Pollution and Token Costs

To locate a single reference document in a SharePoint document library containing 2,000 files across 40 folders, a recursive agent must inspect directory listings across every branch.

Each Graph API response contains hundreds of lines of JSON metadata: @odata.context strings, web URLs, GUIDs, parent references, and timestamps. Passing this raw structural metadata directly into an LLM context window burns thousands of prompt tokens on irrelevant directory strings. By the time the agent locates the target document, a significant portion of its context budget has been consumed by filesystem plumbing rather than substantive content.

Latency Compounding Across Deep Hierarchies

Folder recursion is inherently sequential. An agent cannot know the contents of subfolder C until it inspects folder B, which requires inspecting folder A.

If a document library has an average nesting depth of four levels, resolving the location of a file across multiple branches requires dozens of consecutive HTTP requests. Even under optimal network conditions where each Graph API call completes in 200 ms, recursive tree discovery adds seconds of wall-clock delay before file contents can even be downloaded.

Storage Connectors in Claude Cowork Benchmarks

Performance evaluations of storage connectors in Claude Cowork (published at https://fast.io/benchmarks/) highlight the stark difference between raw connector crawling and indexed workspace retrieval. In those benchmarks, Fastio was measured the fastest and the lowest cost of the providers tested. SharePoint was not measured in Claude Cowork connector benchmarks.

The benchmark results reflect a core engineering principle: autonomous agents perform best when decoupled from raw filesystem crawling. Querying pre-indexed workspaces over dedicated protocols avoids the round-trip latency, rate limits, and token overhead inherent in traversing remote cloud storage APIs.

The solution to SharePoint API traversal bottlenecks is keeping files in SharePoint while syncing target libraries into an intelligent Fast.io workspace. Fast.io functions as the agentic collaboration layer where documents are pre-indexed, searchable by meaning, and accessible to AI agents over the Model Context Protocol.

Cloud Sync Architecture for SharePoint

In this architecture, your organization preserves SharePoint as its primary enterprise document repository. Using Cloud Sync via the OneDrive connector, document libraries sync into Fast.io workspaces:

• Sync Flexibility: Sync operates one-way or two-way, on a schedule or on demand. Sync is never continuous, live, or real-time, preventing partial-write sync collisions.
• Zero Local Disk I/O: Files transfer directly between cloud storage endpoints without requiring intermediary downloads to a developer laptop or local server.
• Automatic Intelligence Mode: Upon arrival in the Fast.io workspace, documents are automatically indexed for hybrid search, combining full-text lexical indexing with semantic vector embeddings.

Decoupled Agent Retrieval Over Remote MCP

Once the SharePoint library is synced to Fast.io, AI agents no longer issue recursive file listing calls. Instead, the agent connects to the remote Fast.io MCP server over Streamable HTTP and executes targeted semantic searches.

The MCP server is hosted remotely at dedicated endpoints depending on client type:

• https://mcp.fast.io/mcp/code for coding agents (Claude Code, Cursor, Gemini CLI, Cline, Devin, GitHub Copilot)
• https://mcp.fast.io/mcp/tools for Claude desktop, web apps, OpenClaw, and general MCP clients
• ChatGPT and Codex connect through the Fastio plugin, with https://mcp.fast.io/mcp/operations as the alternative for a custom MCP server

Clients configure remote connections using Streamable HTTP. For example, in Claude Code, add the connector directly:

claude mcp add --transport http fast-io https://mcp.fast.io/mcp/code

When an agent needs information from the synced SharePoint files, it calls the search tool on /mcp/code:

{
  "method": "tools/call",
  "params": {
    "name": "search",
    "arguments": {
      "query": "enterprise data retention schedule and security guidelines",
      "limit": 3
    }
  }
}

The Fast.io workspace evaluates the query across the indexed corpus and returns focused text extracts accompanied by document citations, file paths, and version identifiers. The agent receives the precise answers required for its task in a single round trip, avoiding directory crawling entirely.

Structured Data Extraction with Metadata Views

For document workflows requiring structured database records, Metadata Views turn unstructured files into queryable spreadsheets. Users describe desired extraction fields in natural language, and AI designs a typed schema across text, integer, decimal, boolean, URL, JSON, and date fields.

Metadata Views process contracts, invoices, specifications, and reports without requiring rigid OCR templates. AI agents can create views, trigger extractions, and query structured records directly over MCP, bridging the gap between raw SharePoint files and structured analytical workflows.

Collaboration, Governance, and Plan Specifications

Fast.io workspaces provide governance for blended human and agent teams:

• Per-File Version History: Every file maintains full version history, allowing instant restoration and auditability during concurrent agent edits.
• Advisory File Locks: Agents acquire, heartbeat, and release file leases using lock-acquire and lock-release on storage_manage, checking status via lock-status on storage. Locks signal active editing while preserving version history.
• Events Feed: Agents subscribe to workspace activity over WebSocket or long-polling (GET /current/activity/poll/{entity_id}) to react as new documents arrive.
• Ownership Transfer: Agents can initialize organizations, configure workspaces, and transfer full ownership to human team members while retaining administrative access.

Monthly plans start with a 30-day free trial, which requires a credit card. Creating an account is free; running shared workspaces requires an organization subscription. Credits meter AI processing, including semantic search, document summarization, and metadata extraction, while storage and seat allocations are fixed with each plan tier:

Credits meter AI work. Plan storage and seat allocations are fixed with each tier, with additional storage, bandwidth, and credit allowances detailed on the Fast.io pricing page.

Deciding how to access SharePoint files depends on whether your software pipeline is performing administrative directory synchronization or supporting autonomous AI reasoning.

When to Use the SharePoint REST API

Choose the SharePoint REST API (/_api/web/) when:

• Maintaining legacy scripts built on the SharePoint Client-Side Object Model (CSOM) or classic PowerShell modules.
• Interacting with on-premises SharePoint Server farms (2016, 2019, or Subscription Edition) that do not support Microsoft Graph.
• Developing SharePoint Framework (SPFx) web parts running inside an authenticated SharePoint browser session where SPHttpClient provides automatic authentication.
• Executing complex CAML queries to filter list items by custom site columns and taxonomy fields.

When to Use Microsoft Graph API

Choose Microsoft Graph (graph.microsoft.com/v1.0/) when:

• Building custom cloud web applications or backend microservices that integrate multiple Microsoft 365 services, such as Microsoft Teams, Outlook, and OneDrive.
• Automating tenant-wide file migrations, permission audits, or compliance archival routines.
• Creating, updating, or deleting SharePoint site collections, document libraries, and drive item sharing permissions.
• Executing delta queries to synchronize incremental document changes into an external database.

When to Use Fast.io Synced Workspaces with MCP

Choose Fast.io Synced Workspaces with remote MCP retrieval when:

• Building AI agents (Claude, GPT-4, Gemini, Cursor, Devin) that need to reason over enterprise documents without getting trapped in directory pagination loops.
• Protecting LLM context windows and reducing token costs by retrieving semantic citations rather than raw JSON file listings.
• Enabling direct collaboration where human team members manage files in SharePoint while AI agents read and write through MCP tools.
• Extracting structured records from unstructured documents at scale using Metadata Views.

Evaluation Matrix

The following comparison summarizes how each approach handles directory enumeration, search capabilities, and agent integration:

By syncing SharePoint document libraries into Fast.io, teams maintain their enterprise storage foundation while providing autonomous agents with the high-speed, citation-backed access required for production workflows.