> ## Documentation Index
> Fetch the complete documentation index at: https://sdk.grid.is/llms.txt
> Use this file to discover all available pages before exploring further.

# Read cell objects and run calculations

> Run calculations in a workbook and retrieve cell objects.

Use this endpoint if you need detailed cell objects that include raw values, value types, format strings, and cell positional offsets. If you only need cell values, try the [`values` endpoint](/api-reference/workbooks/values).


## OpenAPI

````yaml post /v1/workbooks/{id}/calc
openapi: 3.1.0
info:
  title: GRID API
  summary: Spreadsheets run the world. Now you can run spreadsheets.
  description: >-
    GRID's API transforms spreadsheets into powerful, programmable APIs. Our
    platform supports seamless integration of spreadsheet data into your
    applications, supporting dynamic interactions with spreadsheets, including
    real-time data querying with ephemeral updates.
  version: 1.0.0
servers:
  - url: https://api.grid.is
security: []
tags:
  - name: workbooks
    description: Interact with workbooks and their data
paths:
  /v1/workbooks/{id}/calc:
    post:
      tags:
        - workbooks
      summary: Read and write cell values from a workbook
      description: Run calculations in a workbook and retrieve cell objects.
      operationId: calc
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            title: Unique workbook id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CalcRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalcObjectResponse'
        '400':
          description: Error returned when you make a bad request
          content:
            application/json:
              example:
                error_code: invalid_json
                error_message: Bad request
                error_details: RequestJsonParsingFailed
        '403':
          description: Error returned when you don't have permission to query a workbook
          content:
            application/json:
              example:
                error_message: Forbidden
                error_details: Only API keys can access the workbook engine API
        '429':
          description: Error returned when you exceed your API rate limit
          content:
            application/json:
              example:
                error_code: rate_limit_exceeded
                error_message: Rate limit exceeded
                error_details: 'Retry after: 60'
      security:
        - apiKey: []
      x-codeSamples:
        - lang: JavaScript
          source: >-
            import Grid from '@grid-is/api';


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


            const response = await client.workbooks.calc('id', { read: ['A1']
            });


            console.log(response);
        - lang: Python
          source: |-
            from grid_api import Grid

            client = Grid(
                api_key="My API Key",
            )
            response = client.workbooks.calc(
                id="id",
                read=["A1"],
            )
            print(response)
        - lang: Java
          source: |-
            package is.grid.api.example;

            import is.grid.api.client.GridClient;
            import is.grid.api.client.okhttp.GridOkHttpClient;
            import is.grid.api.models.workbooks.WorkbookCalcParams;
            import is.grid.api.models.workbooks.WorkbookCalcResponse;

            public final class Main {
                private Main() {}

                public static void main(String[] args) {
                    GridClient client = GridOkHttpClient.fromEnv();

                    WorkbookCalcParams params = WorkbookCalcParams.builder()
                        .id("id")
                        .addRead("A1")
                        .build();
                    WorkbookCalcResponse response = client.workbooks().calc(params);
                }
            }
components:
  schemas:
    CalcRequest:
      properties:
        apply:
          anyOf:
            - additionalProperties:
                anyOf:
                  - type: integer
                  - type: number
                  - type: string
                  - type: boolean
                  - type: 'null'
                description: >-
                  Excel cell value. This can be a number, string, boolean, or
                  blank
                examples:
                  - 1234
                  - 1234.56
                  - Hello, world!
                  - true
              propertyNames:
                description: >

                  A1-style cell reference, cell range, or formula that
                  references cells in a sheet.

                  References can be relative, mixed, or absolute. References may
                  include a sheet prefix.


                  ```json

                  {
                    "read": [
                      "A1",
                      "Sheet1!A1:B2",
                      "'Loan Calculator'!C32",
                      "$A$1",
                      "=10*10",
                      "=SUM(A:A)"
                    ],
                  }

                  ```
                examples:
                  - A1
                  - Sheet1!A1:B2
                  - '''Loan Calculator''!C32'
                  - $A$1
                  - '=10*10'
                  - '=SUM(A:A)'
              type: object
            - type: 'null'
          title: Apply
          description: >

            Map of cell references to values. The values are written to cells in
            the spreadsheet

            before performing the read operation. You can write numbers,
            strings, and booleans.

            Values applied within a request are temporary and affect only that
            specific request.

            They are not permanently written to the original spreadsheet.


            ```json

            {
              "apply": { "A1": 10, "A2": 2.718, "A3": "Total", "A4": true, "A5": null },
              // ...
            }

            ```
          examples:
            - A1: 100
              A2: 2.718
              A3: Total
              A4: true
        read:
          items:
            type: string
            description: >

              A1-style cell reference, cell range, or formula that references
              cells in a sheet.

              References can be relative, mixed, or absolute. References may
              include a sheet prefix.


              ```json

              {
                "read": [
                  "A1",
                  "Sheet1!A1:B2",
                  "'Loan Calculator'!C32",
                  "$A$1",
                  "=10*10",
                  "=SUM(A:A)"
                ],
              }

              ```
            examples:
              - A1
              - Sheet1!A1:B2
              - '''Loan Calculator''!C32'
              - $A$1
              - '=10*10'
              - '=SUM(A:A)'
          type: array
          title: Read
      type: object
      required:
        - read
      title: CalcRequest
    CalcObjectResponse:
      additionalProperties:
        anyOf:
          - $ref: '#/components/schemas/ReadValue'
          - items:
              $ref: '#/components/schemas/ReadValue'
            type: array
        examples:
          - formatted: €6,378.32
            offset:
              - 0
              - 0
            type: number
            value: 6378.32
      propertyNames:
        description: >

          A1-style cell reference, cell range, or formula that references cells
          in a sheet.

          References can be relative, mixed, or absolute. References may include
          a sheet prefix.


          ```json

          {
            "read": [
              "A1",
              "Sheet1!A1:B2",
              "'Loan Calculator'!C32",
              "$A$1",
              "=10*10",
              "=SUM(A:A)"
            ],
          }

          ```
        examples:
          - A1
          - Sheet1!A1:B2
          - '''Loan Calculator''!C32'
          - $A$1
          - '=10*10'
          - '=SUM(A:A)'
      type: object
      title: CalcObjectResponse
      description: Response type returned by the for /calc query endpoint.
    ReadValue:
      properties:
        type:
          type: string
          enum:
            - blank
            - boolean
            - number
            - string
            - date
            - error
          title: Type
          description: Type of the cell value
          examples:
            - number
        offset:
          prefixItems:
            - type: integer
            - type: integer
          type: array
          maxItems: 2
          minItems: 2
          title: Offset
          description: >-
            Cell position in the spreadsheet, using 0-indexed x/y coordinates.
            Origin [0, 0] is at the top-left
          examples:
            - - 0
              - 0
        value:
          anyOf:
            - type: integer
            - type: number
            - type: string
            - type: boolean
            - type: 'null'
          title: Value
          description: Cell value
          examples:
            - 6378.32
        formatted:
          type: string
          title: Formatted
          description: Formatted cell value
          examples:
            - €6,378.32
        error:
          anyOf:
            - type: string
            - type: 'null'
          title: Error
          default: Human-readable error message if the cell contains an error
      type: object
      required:
        - type
        - offset
        - value
        - formatted
      title: ReadValue
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: JWT

````