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

const client = new Grid({
  apiKey: process.env['GRID_API_TOKEN'], // This is the default and can be omitted
});

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

  console.log(response.apply);
}

main();
{
  "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).

Response

200
application/json

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.