Excel Graph API: How It Works and What It Can Do

Charts & pivot tables · Updated November 16, 2026

The Excel Graph API is the set of Microsoft Graph REST endpoints that lets an application read and change Excel workbooks stored in OneDrive for Business or SharePoint. It can work with workbook ranges, tables, worksheets, and charts; it is not a separate Excel product or a way to control every feature of the desktop application.

What the Excel Graph API is

Microsoft Graph is Microsoft’s unified API for accessing data and services across Microsoft 365. Its Excel endpoints let software interact with supported workbook files through HTTPS requests, rather than opening Excel and automating its interface. An application can, for example, retrieve a worksheet’s values, write data into a range, or create a table for a reporting workflow.

The workbook is still an Excel file, commonly an .xlsx file. Graph addresses the file in a user’s OneDrive for Business or in a SharePoint document library, then exposes workbook objects below that file. A workbook’s worksheets, ranges, tables, and charts are therefore addressed through a drive and file, not as free-standing objects unrelated to a stored workbook.

People often use “Excel API” to mean different things. Microsoft Graph’s Excel REST API is intended for server-side or cloud-connected applications. The Excel JavaScript API is a different interface for Office add-ins that run inside Excel, while Office Scripts automate workbook tasks in supported Microsoft 365 environments. Choosing the right one depends on where the code runs and what it needs to control.

Where workbooks are stored and how requests address them

Excel workbook endpoints are designed for files in OneDrive for Business, SharePoint, and supported Microsoft 365 group drives. They are not a general API for files sitting on a computer’s local disk, and the Excel endpoints do not support personal Microsoft accounts in the same way as business and school accounts. A local file must first be placed in a supported cloud location.

A request usually identifies a workbook by its drive item ID or by a path within a drive. For example, a path-based request can address a workbook named Budget.xlsx in a Documents folder, then ask for its worksheets:

GET /me/drive/root:/Documents/Budget.xlsx:/workbook/worksheets

Once the file is identified, a request can target a particular worksheet, range, table, or chart. A range endpoint can use an address such as A1:B5. Item IDs are often preferable in applications that retain references over time, while paths are convenient for examples and known folder structures. A renamed or moved file can make a previously stored path unusable.

What you can do with workbook endpoints

Graph provides a useful set of operations for common structured workbook tasks. Depending on the object and endpoint, applications can read values and formulas, update cell values, inspect or change worksheet properties, and work with tables and charts. That makes it suitable for synchronizing business data, filling a reporting template, or extracting a small range for another service.

For example, to write two rows into cells A1:B2 on a worksheet identified by its ID, an application can send a PATCH request to the range endpoint with a values array:

PATCH /me/drive/items/{item-id}/workbook/worksheets/{worksheet-id}/range(address='A1:B2')

The JSON request body can be {"values":[["Month","Sales"],["January",1250]]}. The first inner array supplies the first row and the second supplies the next row. The API’s range representation can also expose formulas and other cell properties; read the endpoint documentation for the exact request and response fields because not every property is writable in the same way.

Tables can be useful when the data needs headers and a named, expandable structure rather than an arbitrary cell block. Chart endpoints let applications work with workbook charts, but they do not turn Graph into a general chart-rendering service or reproduce every interactive action available in Excel. The workbook API is strongest when an application needs predictable access to workbook data and common objects.

Authentication, permissions, and access

An application must obtain an OAuth access token for Microsoft Graph and send it in the Authorization header as a bearer token. In typical Excel API scenarios, access is delegated: a signed-in user authorizes the application, and Graph enforces that user’s access to the workbook. Excel workbook endpoints do not generally provide app-only access without a user context, so a background process that must run unattended needs careful evaluation before choosing this API.

The required permission depends on the action and the storage location. Reading workbook information requires read access; changing cells or workbook objects requires appropriate write access. Permissions such as Files.Read or Files.ReadWrite may be relevant, but the correct least-privilege permission should be checked against the specific endpoint and account type in the current Microsoft Graph permissions reference. SharePoint access policies and the user’s file permissions still apply.

For a production integration, use a supported Microsoft authentication library such as MSAL rather than collecting or storing a user’s password. Protect tokens, request only the scopes the application needs, and handle token expiration. A successful sign-in does not guarantee that a user has permission to open a particular workbook.

A practical request workflow

A reliable implementation separates authentication, file selection, workbook operations, and error handling. A simple workflow looks like this:

  1. Register the application in Microsoft Entra ID and configure the appropriate delegated permissions and redirect settings.
  2. Authenticate the user and request a Microsoft Graph access token with the needed scopes.
  3. Locate the workbook in OneDrive for Business or SharePoint, using a drive item ID or a known path.
  4. Call the required workbook endpoint and send JSON using the HTTP method specified by that endpoint.
  5. Check the response, handle errors and throttling, and confirm that a write produced the intended result.

For a sequence of operations on one workbook, a workbook session can help. The application creates a session using the workbook’s createSession endpoint, specifying whether changes should persist, then sends the returned workbook-session-id header on subsequent workbook requests. A persistent session is intended for changes that should be saved to the file; a non-persistent session is temporary and does not save its changes to the workbook. Sessions are useful for grouped operations, but they are not a substitute for handling access conflicts or validating results.

Use the Microsoft Graph v1.0 endpoints where they cover the required operation. Preview or beta endpoints may change and should not be treated as stable production contracts. Microsoft Graph Explorer can help explore requests interactively, but a real application still needs its own authentication flow, permission review, and error handling.

Limits and common problems

The Graph Excel API is not the entire Excel object model. It does not provide a general way to automate the desktop interface, run arbitrary VBA macros, or guarantee support for every feature in a complex workbook. If a task depends on a feature absent from the documented endpoints, do not assume that an equivalent endpoint exists. Check the endpoint coverage and limitations before designing around it.

Failures often arise from the file or account context rather than from the range syntax. Common issues include using a local or unsupported file, addressing the wrong drive item, requesting a worksheet with an outdated ID, missing write permissions, or sending malformed JSON. A workbook may also be unavailable or busy while another process changes it. Inspect the HTTP status code and Graph error response instead of treating every failure as an Excel calculation problem.

  • 401 Unauthorized: Check that the access token is valid, intended for Microsoft Graph, and included in the request.
  • 403 Forbidden: Confirm consent, the delegated permission, and the user’s access to the drive item.
  • 404 Not Found: Recheck the drive, item, worksheet, and path; a moved or renamed file can invalidate a path.
  • 429 Too Many Requests: Respect the Retry-After response header when provided, then retry with backoff rather than sending requests continuously.

For large or complex workbooks, test realistic volumes and concurrent access patterns early. A request that works for a small range may not be an efficient design for repeated cell-by-cell updates. Prefer appropriately sized range operations, avoid unnecessary calls, and plan for retries where the service signals throttling or a temporary failure.

How it compares with other Excel automation options

Use Microsoft Graph when the workbook lives in Microsoft 365 storage and an external application needs to read or update common workbook objects over a network. It is a natural fit for web services and integrations that already use Microsoft identity and Graph. Its cloud-file focus is also a constraint: it is not the best fit for automating a workbook that exists only on a user’s desktop.

The Excel JavaScript API is built for Office add-ins running in Excel. It exposes workbook operations within the add-in context and is often a better fit when a user should interact with a task pane or ribbon command while the workbook is open. Office Scripts are scripts for automating repetitive tasks in supported Excel environments and can be useful in Microsoft 365 workflows, including automation connected to Power Automate.

VBA remains relevant for desktop workbook automation, especially for existing macro-enabled solutions, but it runs in Excel and has different security and deployment considerations. For a simple scheduled data transfer, a purpose-built connector or another Microsoft 365 service may be easier than writing a Graph integration. Compare where the code runs, whether a user must be present, the required workbook features, and how access will be authorized.

Frequently Asked Questions

Is the Excel Graph API free?
There is no separate Excel Graph API license to buy just to make REST calls, but using it requires an eligible Microsoft 365 account and access to the workbook’s storage. Microsoft 365 licensing, tenant policies, and related services can affect what is available, so check the licensing terms for the actual environment.

Can I use the Excel Graph API with a personal OneDrive account?
The Excel workbook endpoints are aimed at work or school accounts and supported business storage, such as OneDrive for Business and SharePoint. Do not assume that a personal OneDrive workbook is supported; confirm current account and endpoint support before building an integration.

Can it run without a user signed in?
Excel workbook APIs generally require delegated permissions and a user context rather than application-only permissions. If a process must run unattended, check whether a supported user-based flow and operational model meet the requirement, or consider another automation approach.

Can the API run VBA macros?
No. Graph can manipulate supported workbook objects, but it is not a remote VBA execution service. If the task depends on a macro, consider whether its logic can be implemented through supported workbook operations, Office Scripts, or a suitable desktop automation design.

Is Microsoft Graph the same as the Excel JavaScript API?
No. Graph is a REST API for applications accessing Microsoft 365 data, including supported cloud workbooks. The Excel JavaScript API is for Office add-ins that run in Excel and interact with the open workbook. Their environments, authentication patterns, and capabilities differ.

Related

Try it: the Percentage Formula Generator: percent of, percent change, increase and decrease, with the formula.

More in Charts & pivot tables

Sources: Function behaviour and menu paths: Microsoft Support documentation for Excel. Method & sources

Spotted an error in this guide? Let us know.