# Microsoft Excel 365

> Create and manage Excel workbooks in OneDrive or SharePoint.

Source: https://cotera.co/docs/reference/tools/individual-tools/microsoft-excel-365

---

**Authentication:** Microsoft OAuth. Requires a connected Microsoft 365 account with access to the relevant Microsoft resources, such as Word, Excel, PowerPoint, OneDrive, SharePoint, Outlook, Calendar, or Teams depending on the tool.

**Note:** Read Range and Add Table Row only support OneDrive (no `driveId` parameter). All other Excel tools support both OneDrive and SharePoint via the optional `driveId` parameter.

***

## Workbook Operations

Create and manage Excel workbooks in OneDrive or SharePoint.

### Create Workbook

Create a new, blank Excel workbook (.xlsx) in OneDrive or SharePoint, optionally with named worksheets.

**Operation Type:** Mutation (Write)

**Parameters:**

* **fileName** `string` (required): The name of the workbook to create, including the .xlsx extension (e.g. `"Q3 Report.xlsx"`)
* **siteId** `string` (optional): SharePoint site ID to save into its default document library. Provide `siteId`, `driveId`, or neither (OneDrive).
* **driveId** `string` (optional): A specific document library drive ID to save into. Omit or null to use the signed-in user's OneDrive.
* **parentItemId** `string` (optional): The drive item ID of the folder to save into. Omit or null to save to the drive root.
* **worksheetNames** `array of strings` (optional): Names for the worksheets to create. Omit or null for a single default "Sheet1".
* **conflictBehavior** `string` (optional, default: `"replace"`): What to do if a file with the same name exists: `"replace"` (default), `"rename"`, or `"fail"`.

**Returns:**

* **id** `string`: ID of the created workbook
* **name** `string`: Final file name (may differ if renamed)
* **webUrl** `string` (nullable): URL to view the workbook in the browser
* **size** `int` (nullable): File size in bytes

**Example Usage:**

```json
{
  "fileName": "Q3 Report.xlsx",
  "worksheetNames": ["Summary", "Data", "Charts"],
  "conflictBehavior": "rename"
}
```

***

## Sheet Operations

Manage worksheets (tabs) within an Excel workbook.

### List Worksheets

List the worksheets (tabs) in an Excel workbook, including their position and visibility.

**Operation Type:** Query (Read)

**Parameters:**

* **fileId** `string` (required): The OneDrive/SharePoint drive item ID of the Excel workbook
* **driveId** `string` (optional): The drive ID containing the workbook (for SharePoint files). Omit or null to use the signed-in user's OneDrive.

**Returns:**

* **worksheets** `array of objects`: The worksheets in the workbook
  * **id** `string`: Worksheet ID
  * **name** `string`: Worksheet name
  * **position** `int` (nullable): Zero-based position of the worksheet in the workbook
  * **visibility** `string` (nullable): Visibility: `Visible`, `Hidden`, or `VeryHidden`

**Example Usage:**

```json
{
  "fileId": "01ABCDEFGHIJKLMNOPQRSTUVWX"
}
```

### Add Worksheet

Add a new worksheet (tab) to an Excel workbook.

**Operation Type:** Mutation (Write)

**Parameters:**

* **fileId** `string` (required): The OneDrive/SharePoint drive item ID of the Excel workbook
* **driveId** `string` (optional): The drive ID containing the workbook (for SharePoint files). Omit or null to use the signed-in user's OneDrive.
* **name** `string` (optional): Name for the new worksheet. Omit or null to let Excel choose a default name.

**Returns:**

* **id** `string`: ID of the created worksheet
* **name** `string`: Name of the created worksheet
* **position** `int` (nullable): Zero-based position of the worksheet in the workbook
* **visibility** `string` (nullable): Visibility: `Visible`, `Hidden`, or `VeryHidden`

**Example Usage:**

```json
{
  "fileId": "01ABCDEFGHIJKLMNOPQRSTUVWX",
  "name": "Q4 Data"
}
```

### Update Worksheet

Rename, reposition, or change the visibility of a worksheet.

**Operation Type:** Mutation (Write)

**Parameters:**

* **fileId** `string` (required): The OneDrive/SharePoint drive item ID of the Excel workbook
* **worksheetIdOrName** `string` (required): Worksheet ID or current name (e.g. `"Sheet1"`)
* **driveId** `string` (optional): The drive ID containing the workbook (for SharePoint files). Omit or null to use the signed-in user's OneDrive.
* **name** `string` (optional): New name for the worksheet. Omit or null to leave unchanged.
* **position** `int` (optional): New zero-based position for the worksheet. Omit or null to leave unchanged.
* **visibility** `string` (optional): New visibility: `"Visible"`, `"Hidden"`, or `"VeryHidden"`. Omit or null to leave unchanged.

**Returns:**

* **id** `string`: Worksheet ID
* **name** `string`: Worksheet name after the update
* **position** `int` (nullable): Zero-based position after the update
* **visibility** `string` (nullable): Visibility after the update

**Example Usage:**

```json
{
  "fileId": "01ABCDEFGHIJKLMNOPQRSTUVWX",
  "worksheetIdOrName": "Sheet1",
  "name": "January",
  "position": 0
}
```

### Delete Worksheet

Delete a worksheet from an Excel workbook.

**Operation Type:** Mutation (Write)

**Parameters:**

* **fileId** `string` (required): The OneDrive/SharePoint drive item ID of the Excel workbook
* **worksheetIdOrName** `string` (required): Worksheet ID or name to delete (e.g. `"Sheet1"`)
* **driveId** `string` (optional): The drive ID containing the workbook (for SharePoint files). Omit or null to use the signed-in user's OneDrive.

**Returns:**

* **deleted** `boolean`: Whether the worksheet was deleted successfully

**Example Usage:**

```json
{
  "fileId": "01ABCDEFGHIJKLMNOPQRSTUVWX",
  "worksheetIdOrName": "OldSheet"
}
```

***

## Range Operations

Read and write cell values, formulas, and formats in a worksheet range.

### Read Range

Read a range of cells from an Excel workbook, returning raw values, formatted text, and formulas.

**Operation Type:** Query (Read)

**Parameters:**

* **fileId** `string` (required): The OneDrive file ID of the Excel workbook
* **worksheetIdOrName** `string` (required): Worksheet ID or name (e.g. `"Sheet1"`)
* **range** `string` (required): Cell range in A1 notation (e.g. `"A1:D10"`)

**Returns:**

* **address** `string` (nullable): Resolved range address
* **rowCount** `int` (nullable): Number of rows in the range
* **columnCount** `int` (nullable): Number of columns in the range
* **values** `array of arrays` (nullable): Cell values as a 2D array
* **text** `array of string arrays` (nullable): Formatted text values as a 2D array
* **formulas** `array of string arrays` (nullable): Cell formulas as a 2D array

**Example Usage:**

```json
{
  "fileId": "01ABCDEFGHIJKLMNOPQRSTUVWX",
  "worksheetIdOrName": "Sheet1",
  "range": "A1:C10"
}
```

### Update Range

Write values, formulas, or number formats to a range of cells. At least one of `values`, `formulas`, or `numberFormat` must be provided.

**Operation Type:** Mutation (Write)

**Parameters:**

* **fileId** `string` (required): The OneDrive/SharePoint drive item ID of the Excel workbook
* **worksheetIdOrName** `string` (required): Worksheet ID or name (e.g. `"Sheet1"`)
* **range** `string` (required): Cell range in A1 notation (e.g. `"A1:D10"`). Must match the shape of the values/formulas provided.
* **driveId** `string` (optional): The drive ID containing the workbook (for SharePoint files). Omit or null to use the signed-in user's OneDrive.
* **values** `array of arrays` (optional): Cell values as a 2D array matching the range dimensions. Omit or null to leave values unchanged.
* **formulas** `array of string arrays` (optional): Cell formulas as a 2D array (e.g. `[["=A1+B1"]]`). Omit or null to leave formulas unchanged.
* **numberFormat** `array of string arrays` (optional): Number formats as a 2D array (e.g. `[["0.00%"]]`). Omit or null to leave formats unchanged.

**Returns:**

* **address** `string` (nullable): Resolved range address
* **rowCount** `int` (nullable): Number of rows in the range
* **columnCount** `int` (nullable): Number of columns in the range

**Example Usage:**

```json
{
  "fileId": "01ABCDEFGHIJKLMNOPQRSTUVWX",
  "worksheetIdOrName": "Sheet1",
  "range": "A1:B2",
  "values": [
    ["Name", "Score"],
    ["Alice", 95]
  ]
}
```

### Clear Range

Clear the contents, formats, or both from a range of cells.

**Operation Type:** Mutation (Write)

**Parameters:**

* **fileId** `string` (required): The OneDrive/SharePoint drive item ID of the Excel workbook
* **worksheetIdOrName** `string` (required): Worksheet ID or name (e.g. `"Sheet1"`)
* **range** `string` (required): Cell range in A1 notation (e.g. `"A1:D10"`)
* **driveId** `string` (optional): The drive ID containing the workbook (for SharePoint files). Omit or null to use the signed-in user's OneDrive.
* **applyTo** `string` (optional, default: `"All"`): What to clear: `"All"` (default), `"Formats"`, or `"Contents"` (values only).

**Returns:**

* **cleared** `boolean`: Whether the range was cleared successfully

**Example Usage:**

```json
{
  "fileId": "01ABCDEFGHIJKLMNOPQRSTUVWX",
  "worksheetIdOrName": "Sheet1",
  "range": "A1:D10",
  "applyTo": "Contents"
}
```

***

## Table Operations

Create and manage structured tables and their rows within an Excel workbook.

### List Tables

List the tables in an Excel workbook, optionally scoped to a single worksheet.

**Operation Type:** Query (Read)

**Parameters:**

* **fileId** `string` (required): The OneDrive/SharePoint drive item ID of the Excel workbook
* **driveId** `string` (optional): The drive ID containing the workbook (for SharePoint files). Omit or null to use the signed-in user's OneDrive.
* **worksheetIdOrName** `string` (optional): Worksheet ID or name to scope the listing to a single sheet. Omit or null to list all tables in the workbook.

**Returns:**

* **tables** `array of objects`: The tables in the workbook or worksheet
  * **id** `string`: Table ID
  * **name** `string`: Table name
  * **showHeaders** `boolean` (nullable): Whether the header row is shown
  * **showTotals** `boolean` (nullable): Whether the totals row is shown
  * **style** `string` (nullable): Table style name

**Example Usage:**

```json
{
  "fileId": "01ABCDEFGHIJKLMNOPQRSTUVWX",
  "worksheetIdOrName": "Sheet1"
}
```

### Add Table

Create a table over a range of cells in a worksheet.

**Operation Type:** Mutation (Write)

**Parameters:**

* **fileId** `string` (required): The OneDrive/SharePoint drive item ID of the Excel workbook
* **worksheetIdOrName** `string` (required): Worksheet ID or name that contains the range (e.g. `"Sheet1"`)
* **address** `string` (required): The range the table covers, in A1 notation (e.g. `"A1:D5"`)
* **hasHeaders** `boolean` (required, default: `true`): Whether the first row of the range is a header row
* **driveId** `string` (optional): The drive ID containing the workbook (for SharePoint files). Omit or null to use the signed-in user's OneDrive.

**Returns:**

* **id** `string`: ID of the created table
* **name** `string`: Name of the created table
* **showHeaders** `boolean` (nullable): Whether the header row is shown
* **style** `string` (nullable): Table style name

**Example Usage:**

```json
{
  "fileId": "01ABCDEFGHIJKLMNOPQRSTUVWX",
  "worksheetIdOrName": "Sheet1",
  "address": "A1:D10",
  "hasHeaders": true
}
```

### Delete Table

Delete a table from an Excel workbook. The underlying cell values remain after deletion.

**Operation Type:** Mutation (Write)

**Parameters:**

* **fileId** `string` (required): The OneDrive/SharePoint drive item ID of the Excel workbook
* **tableIdOrName** `string` (required): Table ID or name to delete (e.g. `"Table1"`)
* **driveId** `string` (optional): The drive ID containing the workbook (for SharePoint files). Omit or null to use the signed-in user's OneDrive.

**Returns:**

* **deleted** `boolean`: Whether the table was deleted successfully

**Example Usage:**

```json
{
  "fileId": "01ABCDEFGHIJKLMNOPQRSTUVWX",
  "tableIdOrName": "SalesData"
}
```

### List Table Rows

List the data rows of a table in an Excel workbook.

**Operation Type:** Query (Read)

**Parameters:**

* **fileId** `string` (required): The OneDrive/SharePoint drive item ID of the Excel workbook
* **tableIdOrName** `string` (required): Table ID or name to read rows from (e.g. `"Table1"`)
* **driveId** `string` (optional): The drive ID containing the workbook (for SharePoint files). Omit or null to use the signed-in user's OneDrive.

**Returns:**

* **rows** `array of objects`: The data rows of the table
  * **index** `int` (nullable): Zero-based index of the row within the table
  * **values** `array of arrays` (nullable): Row values (a single-row 2D array)

**Example Usage:**

```json
{
  "fileId": "01ABCDEFGHIJKLMNOPQRSTUVWX",
  "tableIdOrName": "SalesData"
}
```

### Add Table Row

Add one or more rows to an existing table in an Excel workbook.

**Operation Type:** Mutation (Write)

**Parameters:**

* **fileId** `string` (required): The OneDrive file ID of the Excel workbook
* **worksheetIdOrName** `string` (required): Worksheet ID or name (e.g. `"Sheet1"`)
* **tableIdOrName** `string` (required): Table ID or name within the worksheet (e.g. `"Table1"`)
* **values** `array of arrays` (required): Row values as a 2D array — each inner array is one row and must match the table's column count (e.g. `[["Alice", 42], ["Bob", 37]]`)

**Returns:**

* **index** `int` (nullable): Zero-based index of the added row
* **values** `array of arrays` (nullable): Values of the added row as returned by the API

**Example Usage:**

```json
{
  "fileId": "01ABCDEFGHIJKLMNOPQRSTUVWX",
  "worksheetIdOrName": "Sheet1",
  "tableIdOrName": "SalesData",
  "values": [["Alice", "Engineering", 42]]
}
```

### Update Table Row

Update the values of a table row by its zero-based index.

**Operation Type:** Mutation (Write)

**Parameters:**

* **fileId** `string` (required): The OneDrive/SharePoint drive item ID of the Excel workbook
* **tableIdOrName** `string` (required): Table ID or name (e.g. `"Table1"`)
* **index** `int` (required): Zero-based index of the data row to update (from List Table Rows)
* **values** `array of arrays` (required): New row values as a single-row 2D array (e.g. `[["a", "b", "c"]]`)
* **driveId** `string` (optional): The drive ID containing the workbook (for SharePoint files). Omit or null to use the signed-in user's OneDrive.

**Returns:**

* **index** `int` (nullable): Index of the updated row
* **values** `array of arrays` (nullable): Values of the updated row

**Example Usage:**

```json
{
  "fileId": "01ABCDEFGHIJKLMNOPQRSTUVWX",
  "tableIdOrName": "SalesData",
  "index": 2,
  "values": [["Bob", "Marketing", 55]]
}
```

### Delete Table Row

Delete a table row by its zero-based index from an Excel workbook.

**Operation Type:** Mutation (Write)

**Parameters:**

* **fileId** `string` (required): The OneDrive/SharePoint drive item ID of the Excel workbook
* **tableIdOrName** `string` (required): Table ID or name (e.g. `"Table1"`)
* **index** `int` (required): Zero-based index of the data row to delete (from List Table Rows)
* **driveId** `string` (optional): The drive ID containing the workbook (for SharePoint files). Omit or null to use the signed-in user's OneDrive.

**Returns:**

* **deleted** `boolean`: Whether the row was deleted successfully

**Example Usage:**

```json
{
  "fileId": "01ABCDEFGHIJKLMNOPQRSTUVWX",
  "tableIdOrName": "SalesData",
  "index": 3
}
```

***

## Chart Operations

Create, update, and render charts on Excel worksheets.

### List Charts

List the charts on a worksheet in an Excel workbook.

**Operation Type:** Query (Read)

**Parameters:**

* **fileId** `string` (required): The OneDrive/SharePoint drive item ID of the Excel workbook
* **worksheetIdOrName** `string` (required): Worksheet ID or name to list charts from (e.g. `"Sheet1"`)
* **driveId** `string` (optional): The drive ID containing the workbook (for SharePoint files). Omit or null to use the signed-in user's OneDrive.

**Returns:**

* **charts** `array of objects`: The charts on the worksheet
  * **id** `string`: Chart ID
  * **name** `string`: Chart name
  * **height** `number` (nullable): Chart height in points
  * **width** `number` (nullable): Chart width in points
  * **top** `number` (nullable): Distance from the top of the worksheet in points
  * **left** `number` (nullable): Distance from the left of the worksheet in points

**Example Usage:**

```json
{
  "fileId": "01ABCDEFGHIJKLMNOPQRSTUVWX",
  "worksheetIdOrName": "Sheet1"
}
```

### Add Chart

Add a chart to a worksheet from a range of data.

**Operation Type:** Mutation (Write)

**Parameters:**

* **fileId** `string` (required): The OneDrive/SharePoint drive item ID of the Excel workbook
* **worksheetIdOrName** `string` (required): Worksheet ID or name to add the chart to (e.g. `"Sheet1"`)
* **type** `string` (required): Chart type, e.g. `"ColumnClustered"`, `"ColumnStacked"`, `"BarClustered"`, `"Line"`, `"LineMarkers"`, `"Pie"`.
* **sourceData** `string` (required): The range that holds the chart data, in A1 notation (e.g. `"A1:B10"`)
* **driveId** `string` (optional): The drive ID containing the workbook (for SharePoint files). Omit or null to use the signed-in user's OneDrive.
* **seriesBy** `string` (optional): How to plot the series: `"Auto"` (default), `"Columns"`, or `"Rows"`. Omit or null for Auto.

**Returns:**

* **id** `string`: ID of the created chart
* **name** `string`: Name of the created chart
* **height** `number` (nullable): Chart height in points
* **width** `number` (nullable): Chart width in points
* **top** `number` (nullable): Distance from the top of the worksheet in points
* **left** `number` (nullable): Distance from the left of the worksheet in points

**Example Usage:**

```json
{
  "fileId": "01ABCDEFGHIJKLMNOPQRSTUVWX",
  "worksheetIdOrName": "Sheet1",
  "type": "ColumnClustered",
  "sourceData": "A1:B10",
  "seriesBy": "Columns"
}
```

### Update Chart

Rename or resize/reposition a chart on a worksheet.

**Operation Type:** Mutation (Write)

**Parameters:**

* **fileId** `string` (required): The OneDrive/SharePoint drive item ID of the Excel workbook
* **worksheetIdOrName** `string` (required): Worksheet ID or name that contains the chart (e.g. `"Sheet1"`)
* **chartName** `string` (required): The current name (or ID) of the chart to update
* **driveId** `string` (optional): The drive ID containing the workbook (for SharePoint files). Omit or null to use the signed-in user's OneDrive.
* **name** `string` (optional): New name for the chart. Omit or null to leave unchanged.
* **height** `number` (optional): New height in points. Omit or null to leave unchanged.
* **width** `number` (optional): New width in points. Omit or null to leave unchanged.
* **top** `number` (optional): New distance from the top of the worksheet in points. Omit or null to leave unchanged.
* **left** `number` (optional): New distance from the left of the worksheet in points. Omit or null to leave unchanged.

**Returns:**

* **id** `string`: Chart ID
* **name** `string`: Chart name after the update
* **height** `number` (nullable): Chart height in points
* **width** `number` (nullable): Chart width in points
* **top** `number` (nullable): Distance from the top of the worksheet in points
* **left** `number` (nullable): Distance from the left of the worksheet in points

**Example Usage:**

```json
{
  "fileId": "01ABCDEFGHIJKLMNOPQRSTUVWX",
  "worksheetIdOrName": "Sheet1",
  "chartName": "Chart 1",
  "name": "Q3 Revenue",
  "height": 300,
  "width": 500
}
```

### Delete Chart

Delete a chart from a worksheet in an Excel workbook.

**Operation Type:** Mutation (Write)

**Parameters:**

* **fileId** `string` (required): The OneDrive/SharePoint drive item ID of the Excel workbook
* **worksheetIdOrName** `string` (required): Worksheet ID or name that contains the chart (e.g. `"Sheet1"`)
* **chartName** `string` (required): The name (or ID) of the chart to delete
* **driveId** `string` (optional): The drive ID containing the workbook (for SharePoint files). Omit or null to use the signed-in user's OneDrive.

**Returns:**

* **deleted** `boolean`: Whether the chart was deleted successfully

**Example Usage:**

```json
{
  "fileId": "01ABCDEFGHIJKLMNOPQRSTUVWX",
  "worksheetIdOrName": "Sheet1",
  "chartName": "Chart 1"
}
```

### Get Chart Image

Render a worksheet chart as a base64-encoded PNG image.

**Operation Type:** Query (Read)

**Parameters:**

* **fileId** `string` (required): The OneDrive/SharePoint drive item ID of the Excel workbook
* **worksheetIdOrName** `string` (required): Worksheet ID or name that contains the chart (e.g. `"Sheet1"`)
* **chartName** `string` (required): The name (or ID) of the chart to render
* **driveId** `string` (optional): The drive ID containing the workbook (for SharePoint files). Omit or null to use the signed-in user's OneDrive.
* **width** `int` (optional): Desired image width in pixels. Omit or null for the default size.
* **height** `int` (optional): Desired image height in pixels. Omit or null for the default size.
* **fittingMode** `string` (optional): How the chart fits the requested dimensions: `"Fit"`, `"FitAndCenter"`, or `"Fill"`. Only applied when both `width` and `height` are set.

**Returns:**

* **base64Image** `string` (nullable): The chart rendered as a base64-encoded PNG string
* **dataUri** `string` (nullable): The image as a data URI (`data:image/png;base64,...`)

**Example Usage:**

```json
{
  "fileId": "01ABCDEFGHIJKLMNOPQRSTUVWX",
  "worksheetIdOrName": "Sheet1",
  "chartName": "Q3 Revenue",
  "width": 800,
  "height": 600,
  "fittingMode": "Fit"
}
```