Skip to main content
POST
/
v1
/
workbooks
/
{id}
/
query
JavaScript
import Grid from '@grid-is/api';

const client = new Grid({
  apiKey: 'My API Key',
});

const response = await client.workbooks.query('id', { read: ['A1', 'Sheet2!B3', '=SUM(A1:A4)'] });

console.log(response.apply);
{
  "apply": [
    {
      "target": "<string>",
      "value": 123,
      "originalValue": 123
    }
  ],
  "read": [
    {
      "source": "<string>",
      "type": "<string>",
      "data": [
        [
          {
            "t": "b",
            "v": 123,
            "r": "<string>",
            "z": "<string>",
            "w": "<string>"
          }
        ]
      ]
    }
  ],
  "goalSeek": {
    "targetCell": "<string>",
    "targetValue": 123,
    "controlCell": "<string>",
    "solution": 123
  }
}
This endpoint offers more control and flexibility compared to the calc and values endpoints. While all three endpoints allow you to read and write cell values from a workbook, the query endpoint provides several advanced capabilities that give developers greater control over data manipulation and retrieval:
  • Goal seeking
  • Organise data by rows or columns
  • Use structured request parameters
For most use-cases, the calc or values endpoints provide a simpler, more streamlined interface that’s easier to work with. However, when you need greater control, the query endpoint becomes essential.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
id
string
required

Body

application/json

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).

​
read
(string | ReferenceObject · object)[]
required

Cell references to read from the workbook and return to the client

A reference to a range of spreadsheet cells

Example:

"Sheet1!A1:B2"

​
options
QueryRequestOptions · object

Options to choose the structure of the returned data

​
apply
DataTransformation · object[] | null

Cells to update before reading. Note that the API has no state and any changes made are cleared after each request

Example:
[{ "target": "A2", "value": 1234 }]
​
goalSeek
QueryRequestGoalSeek · object

Goal seek. Use this to calculate the required input value for a formula to achieve a specified target result. Useful when the desired outcome is known, but the corresponding input is not

Response

Successful Response

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 · object[] | null
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

​
read
DataTable · object[]
required

Details on the values that were read from the workbook cells

​
goalSeek
QueryResponseGoalSeek · object

Results of the goal seek operation