---
title: "Read File"
description: "Read worksheet data from an Excel file stored in OneDrive or SharePoint."
icon: "file-excel"
---

The **Excel — Read File** step reads the used range of one or more worksheets from an Excel file in OneDrive or SharePoint. Use it whenever an agent needs the actual cell values from a spreadsheet — to feed an AI model, drive downstream branching, or transform the data.

For converting a whole document to markdown text (PDF, Word, Excel, etc.), use the [MarkItDown](/building-and-deploying-agents/agent-basics/markitdown-step) step instead.

---

## How it works

The step uses the Microsoft Graph API to read the **used range** of each requested worksheet — the rectangular region from `A1` to the last cell that contains data. Empty trailing rows and columns are not returned.

To keep payloads predictable, the step caps the number of rows and columns it reads. When a worksheet exceeds the cap, the response is **truncated** and flagged so downstream steps can handle the partial result gracefully.

---

## Prerequisites

- The **OneDrive Excel** steps must be enabled on your workspace (feature flag: `step-sdk-onedrive-excel`).
- A **Microsoft OAuth credential** with at least read access to the file.
- The Excel file already exists at the configured **Path**.

---

## Inputs

| Parameter | Required | Description |
|-----------|----------|-------------|
| **Credential** | Yes | The Microsoft OAuth credential used to access the file. |
| **Path** | Yes | The file path in OneDrive, for example `/Documents/MySpreadsheet.xlsx`. |
| **Worksheet Name** | No | The worksheet to read. Leave empty to read every worksheet in the file. |
| **Max Rows** | No | The maximum number of rows to read per worksheet. Defaults to **1000**. Range: 1–100,000. |
| **Max Columns** | No | The maximum number of columns to read per worksheet. Defaults to **100**. Range: 1–16,384. |

---

## Outputs

| Variable | Type | Description |
|----------|------|-------------|
| `Worksheets` | `array` | One entry per worksheet read. Each entry includes `Id`, `Name`, and a `UsedRange` object. |
| `TotalCount` | `int` | The total number of worksheets returned. |
| `WasTruncated` | `bool` | `true` when at least one worksheet exceeded the **Max Rows** / **Max Columns** caps. |
| `TruncationMessage` | `string \| null` | A human-readable description of what was truncated, when `WasTruncated` is `true`. |

Each worksheet entry exposes:

| Field | Description |
|-------|-------------|
| `Id` | The Graph-assigned worksheet identifier. |
| `Name` | The worksheet name (the tab label in Excel). |
| `UsedRange.Address` | The range that was read, for example `A1:D250`. |
| `UsedRange.RowCount` | The number of rows in the used range. |
| `UsedRange.ColumnCount` | The number of columns in the used range. |
| `UsedRange.Values` | A 2D array of cell values, row-major. Cell values may be strings, numbers, booleans, or `null`. |

Reference the data with standard expression syntax, for example:

- `{{Steps.Read_File.Worksheets[0].UsedRange.Values}}`
- `{{Steps.Read_File.WasTruncated}}`

---

## Examples

### 1) Read a specific worksheet

- **Path:** `/Reports/Quarterly Summary.xlsx`
- **Worksheet Name:** `Q1`
- **Max Rows:** `500`

Then pass `{{Steps.Read_File.Worksheets[0].UsedRange.Values}}` into an AI model prompt for analysis.

### 2) Read every worksheet in a file

- **Path:** `/Imports/Customers.xlsx`
- **Worksheet Name:** *(leave empty)*

Use a Loop step to iterate over `{{Steps.Read_File.Worksheets}}` and process each one.

### 3) Guard against truncation

Branch downstream:

- If `{{Steps.Read_File.WasTruncated}}` is `true` → take a fallback path (warn the user, log the truncation, or split the file).
- Else → continue with the full dataset.

---

## Notes and limitations

- **Used range only.** Cells with formatting but no value are still considered empty and are not included in the used range.
- **Hidden worksheets** are returned along with visible ones. Filter on the worksheet name if you need to exclude them.
- **Pivot tables and charts** are not exported — only cell values from the underlying range.
- **Formulas return their cached value**, not the formula text.
- **Bulk reads have a soft Graph limit.** If you regularly exceed it, lower the caps and read worksheets one at a time.
