---
title: "Query workbook data"
method: POST
path: "/v1/workbooks/{id}/query"
tags: ["workbooks"]
---

# Query workbook data

`POST /v1/workbooks/{id}/query`

Read cell data or apply temporary changes.

Send a JSON object with a `read` key to read values from cells and formulas. Optionally, use
the `apply` key to update cells before reading.

## Path parameters

- `id` string, required

## Request body

- QueryRequest — Defines a request to read workbook data and, optionally, apply temporary changes. It includes `read` (required cell references or formulas), `apply` (optional transient updates to cells), and `options` (optional settings for the structure of returned data).
  - `options` QueryRequestOptions — Defines settings for configuring query results.
    - `axis` 'rows' | 'columns', nullable — Determines if data is outputted as rows or columns
  - `apply` DataTransformation[], nullable — Cells to update before reading. Note that the API has no state and any changes made are cleared after each request
    - `target` union, required — Reference for the cell to write to
      - string — A1-style string reference with optional sheet prefix
      - ReferenceObject — A reference to a range of spreadsheet cells.
        - `cells` string, required — Unprefixed A1-style range, id, or name
        - `sheet` string, nullable, required — Name of the sheet to reference
    - `value` union, required — Value to write to the target cell
      - integer
      - number
      - string
      - boolean
  - `goalSeek` QueryRequestGoalSeek — Goal seek. Use this to calculate the required input value for a formula to achieve a specified target result. This is particularly useful when the desired outcome is known, but the corresponding input is not.
    - `targetCell` union, required — Reference for the cell that contains the formula you want to resolve
      - string — A1-style string reference with optional sheet prefix
      - ReferenceObject — A reference to a range of spreadsheet cells.
        - `cells` string, required — Unprefixed A1-style range, id, or name
        - `sheet` string, nullable, required — Name of the sheet to reference
    - `targetValue` union, required — The value you want the formula to return
      - integer
      - number
    - `controlCell` union, required — Reference for the cell that will contain the solution
      - string — A1-style string reference with optional sheet prefix
      - ReferenceObject — A reference to a range of spreadsheet cells.
        - `cells` string, required — Unprefixed A1-style range, id, or name
        - `sheet` string, nullable, required — Name of the sheet to reference
  - `read` union[], required — Cell references to read from the workbook and return to the client
    - union — A reference to a range of spreadsheet cells
      - string — A1-style string reference with optional sheet prefix
      - ReferenceObject — A reference to a range of spreadsheet cells.
        - `cells` string, required — Unprefixed A1-style range, id, or name
        - `sheet` string, nullable, required — Name of the sheet to reference

## Response `200`

Successful Response

- QueryResponse — Contains the results of a workbook query, including `read` (queried cell data) and `apply` (details of temporary changes applied). Note that the API has no state and any changes made are cleared after each request.
  - `apply` QueryResponseApply[], nullable, required — Confirmation of the changes that were applied to the spreadsheet. Note that the API has no state and any changes made are cleared after each request
    - `target` string, required — A1-style reference for the cell that was updated
    - `value` union, required — New value of the cell
      - integer
      - number
      - string
      - boolean
    - `originalValue` union, required — Original value of the cell before applying the new value
      - integer
      - number
      - string
      - boolean
  - `goalSeek` QueryResponseGoalSeek — Results of a goal seek operation.
    - `targetCell` string, required — Reference for the cell that contains the formula you wanted to resolve
    - `targetValue` union, required — The value you wanted the formula to return
      - integer
      - number
    - `controlCell` string, required — Reference for the cell that contains the solution
    - `solution` union — The result of the formula
      - integer
      - number
  - `read` DataTable[], required — Details on the values that were read from the workbook cells
    - `source` string, required — A1-style reference for the cell or cells that were updated
    - `type` 'dataTable', required
    - `data` array[], required
      - union[]
        - union
          - ValueCell — Represents a single workbook cell, including its value (`v`), cell reference (`r`), type (`t`), number format (`z`), and formatted text (`w`).
            - `r` string, nullable — Relative A1-based cell reference. This property only appears when there's a real cell behind the value
            - `t` 'b' | 'n' | 'd' | 's', required — Specifies the type of a workbook cell. Possible values include `b` (boolean), `n` (number), `d` (date), and `s` (string).
            - `v` union, required — Underlying cell value
              - …
            - `z` string, nullable — Number format associated with the cell
            - `w` string, nullable — Formatted cell value
          - ErrorCell — Represents a workbook cell with an error. It includes the cell reference (`r`), type (`t`, always `e`), value (`v`), and an optional error code (`e`). It provides details for identifying and understanding errors in workbook data.
            - `r` string, nullable — Relative A1-based cell reference. This property only appears when there's a real cell behind the value
            - `t` 'e', required — Data type of the cell value (always 'e' for 'error')
            - `v` string, required — Underlying cell value
            - `e` string, nullable — Description of the error
          - EmptyCell — Cells that have no content but hold metadata like comments.
            - `r` string, nullable — Relative A1-based cell reference. This property only appears when there's a real cell behind the value
            - `t` 'z', required — Data type of the cell value (always 'z' for 'empty cell')

## Other responses

- `400` — Error returned when you make a bad request
- `403` — Error returned when you don't have permission to query a workbook
- `429` — Error returned when you exceed your API rate limit

---

[API](https://skmtc.net/grid-is/apis/grid-api.md) · [All operations](https://skmtc.net/grid-is/apis/grid-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/grid-is/grid-api/revisions/2f55490ab23d/schema)