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": "Sheet1!A1:B2",
      "value": 123,
      "originalValue": 123
    }
  ],
  "goalSeek": {
    "targetCell": "Sheet1!A1:B2",
    "targetValue": 123,
    "controlCell": "Sheet1!A1:B2",
    "solution": 123
  },
  "read": [
    {
      "source": "Sheet1!A1:B2",
      "type": "<string>",
      "data": [
        [
          {
            "r": "<string>",
            "t": "b",
            "v": 123,
            "z": "<string>",
            "w": "<string>"
          }
        ]
      ]
    }
  ]
}
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
Read · array
required

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

Examples:
["A1", "Sheet2!B3", "=SUM(A1:A4)"]
​
options
object | null

Options to choose the structure of the returned data Defines settings for configuring query results.

​
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

Examples:
[{ "target": "A2", "value": 1234 }]
​
goalSeek
object | null

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

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
object | null

Results of the goal seek operation Results of a goal seek operation.

⌘I