readCalculatedValues
Read cell values, formula results, and lookups from spreadsheets, and optionally apply temporary values for what-if calculations. The ‘read’ array accepts cell references, ranges, and formulas. Use formulas like XLOOKUP, QUERY, AVERAGE, etc. directly in ‘read’ to find and compute values in a single call.
Examples:
- Read cells: { “read”: [“A1”, “B1:B10”, “Sheet2!C5”] }
- Lookup: { “read”: [“=XLOOKUP(“Revenue”, A1:A10, B1:B10)”] }
- Filtered average: { “read”: [“=QUERY(Sheet1!A1:D100, “SELECT AVG(D) WHERE A = ‘Category1’”)”] }
- What-if: { “read”: [“C8”], “apply”: [{ “cell”: “B1”, “value”: 100 }] }
Large ranges are automatically truncated. When a range entry is truncated the response includes nextOffset — call again with cursors: { "<same expression>": <nextOffset> } to read the next page.
| Parameter | Type | Description | |
|---|---|---|---|
read | string[] | required | Cell references, ranges, or formulas to read. Examples: “A1”, “B1:B10”, “Sheet1!C5”, “=XLOOKUP(“Revenue”, A1:A10, B1:B10)”, “=AVERAGE(C1:C10)“ |
apply | object[] | optional | Temporary values to apply before reading (not persisted) |
apply[].cell | string | required | |
apply[].value | string | number | boolean | null | required | |
cursors | record<string, integer> | optional | Optional pagination cursors keyed by entries in read. Pass nextOffset from a previous truncated response to continue paging through that range. Formula entries (those starting with =) ignore cursors. |