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

# Render a chart using workbook data



## OpenAPI

````yaml post /v1/workbooks/{id}/chart
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}/chart:
    post:
      tags:
        - workbooks
      summary: Render a chart using workbook data
      operationId: get_workbook_chart
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            title: Unique workbook id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChartRequest'
      responses:
        '200':
          description: Chart rendered as an image
          content:
            image/png:
              schema:
                type: string
                format: binary
            image/svg+xml:
              schema:
                type: string
        '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.renderChart('id', { chart:
            {} });


            console.log(response);


            const content = await response.blob();

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

            client = Grid(
                api_key="My API Key",
            )
            response = client.workbooks.render_chart(
                id="id",
                chart={},
            )
            print(response)
            content = response.read()
            print(content)
        - 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.core.http.HttpResponse;
            import is.grid.api.models.workbooks.WorkbookRenderChartParams;

            public final class Main {
                private Main() {}

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

                    WorkbookRenderChartParams params = WorkbookRenderChartParams.builder()
                        .id("id")
                        .chart(WorkbookRenderChartParams.Chart.builder().build())
                        .build();
                    HttpResponse response = client.workbooks().renderChart(params);
                }
            }
components:
  schemas:
    ChartRequest:
      properties:
        apply:
          anyOf:
            - items:
                $ref: '#/components/schemas/DataTransformation'
              type: array
            - type: 'null'
          title: Apply
          description: Cells to update before rendering the chart.
          examples:
            - - target: A2
                value: 1234
        chart:
          $ref: '#/components/schemas/ChartRenderOptions'
        width:
          anyOf:
            - type: integer
            - type: 'null'
          title: Width
          description: >-
            Width of the chart image in pixels. If not given, a width of 764px
            is used. A chart's height cannot be set explicitly because it will
            differ depending upon chart type, title, legend, axis labels, and so
            on.
        matte:
          anyOf:
            - type: string
            - type: 'null'
          title: Matte
          description: >-
            Hex color code for the chart's background matte, e.g. '#FFFFFF' for
            white, if not specified, the chart will have a transparent
            background. Note, this is currently only supported for PNG images.
          default: ''
          examples:
            - '#FFFFFF'
            - '#FFF'
            - '#fff'
      type: object
      required:
        - chart
      title: ChartRequest
      description: Options for rendering a chart from workbook data.
    DataTransformation:
      properties:
        target:
          anyOf:
            - type: string
              description: A1-style string reference with optional sheet prefix
              examples:
                - Sheet1!A1:B2
                - '''Loan Calculator''!C32'
            - $ref: '#/components/schemas/ReferenceObject'
          title: Target
          description: Reference for the cell to write to
        value:
          anyOf:
            - type: integer
            - type: number
            - type: string
            - type: boolean
            - type: 'null'
          title: Value
          description: Value to write to the target cell
      type: object
      required:
        - target
        - value
      title: DataTransformation
      description: >-
        Specifies a temporary change to a workbook cell, including the `target`
        cell reference and the

        `value` to apply. The API has no state, and so any changes made are
        cleared after each request.
    ChartRenderOptions:
      properties:
        data:
          anyOf:
            - type: string
            - type: 'null'
          title: Data
          description: Chart data range, prefixed with an equals sign
          examples:
            - '=C2:C142'
        dataLines:
          anyOf:
            - type: string
            - type: 'null'
          title: Datalines
          description: >-
            Chart data range, prefixed with an equals sign, used for lines in a
            combo chart
          examples:
            - '=C2:C142'
        type:
          anyOf:
            - $ref: '#/components/schemas/SupportedChartTypes'
            - type: 'null'
          description: Type of chart to render
          default: line
        format:
          anyOf:
            - $ref: '#/components/schemas/SupportedImageTypes'
            - type: 'null'
          description: File format to use for the chart image
          default: png
        numberFormat:
          anyOf:
            - type: string
            - type: 'null'
          title: Numberformat
          description: Number format pattern used for formatting labels on the chart.
          default: ''
          examples:
            - '#,##0.0'
            - 0.0%
        values:
          anyOf:
            - $ref: '#/components/schemas/SupportedValueLabelTypes'
            - type: 'null'
          description: How to label individual data values on the chart
          default: none
        labels:
          anyOf:
            - type: string
            - type: 'null'
          title: Labels
          description: >-
            Range of cells to use as the chart's x-axis labels, prefixed with an
            equals sign
          examples:
            - '=B2:B142'
        legend:
          anyOf:
            - type: string
            - type: 'null'
          title: Legend
          description: >-
            Range of cells to use as the chart's legend labels, prefixed with an
            equals sign
          examples:
            - '=D2:D142'
        legendLines:
          anyOf:
            - type: string
            - type: 'null'
          title: Legendlines
          description: >-
            Range of cells to use as the chart's line labels in the legend,
            prefixed with an equals sign
          examples:
            - '=E2:E142'
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
          description: Cell reference to use as the chart's title. Can also be plain text.
          examples:
            - '=A1'
            - Monthly inflation rate
        subtitle:
          anyOf:
            - type: string
            - type: 'null'
          title: Subtitle
          description: >-
            Cell reference to use as the chart's subtitle. Can also be plain
            text.
          examples:
            - '=B4'
            - Sales Performance, Q1 2025
        footnote:
          anyOf:
            - type: string
            - type: 'null'
          title: Footnote
          description: >-
            Cell reference to use as the chart's footnote text. Can also be
            plain text.
          examples:
            - '=H13'
            - 'Data source: Internal CRM'
        colorByPoint:
          anyOf:
            - type: string
            - type: 'null'
          title: Colorbypoint
          description: Vary colors by point rather than series.
          default: 'false'
        dir:
          anyOf:
            - $ref: '#/components/schemas/SupportedDirTypes'
            - type: 'null'
          description: Series orientation when reading data.
          examples:
            - row
        stacked:
          anyOf:
            - $ref: '#/components/schemas/SupportedBooleanTypes'
            - type: 'null'
          description: Whether to display series stacked or grouped
          default: 'false'
        legendVisible:
          anyOf:
            - $ref: '#/components/schemas/SupportedBooleanTypes'
            - type: 'null'
          description: Whether to display a chart legend
        blanks:
          anyOf:
            - $ref: '#/components/schemas/SupportedBlankTypes'
            - type: 'null'
          description: How breaks or gaps in the series are handled
          default: gap
        interpolate:
          anyOf:
            - $ref: '#/components/schemas/SupportedInterpolationTypes'
            - type: 'null'
          description: How a line is interpolated between values
          default: linear
        chartColors:
          anyOf:
            - type: string
            - type: 'null'
          title: Chartcolors
          description: >-
            An Excel array expression that returns a 1-dimensional list of HTML
            color strings
          examples:
            - '={"#C40";"#03F"}'
        sortBy:
          anyOf:
            - type: integer
            - type: 'null'
          title: Sortby
          description: >-
            The number of which series the data should be sorted by (e.g. 1 for
            the first series).
        sortOrder:
          anyOf:
            - $ref: '#/components/schemas/SupportedSortDirections'
            - type: 'null'
          description: The sorting direction when the sortBy property is set.
        axisValue:
          anyOf:
            - $ref: '#/components/schemas/ValueAxisOptions'
            - type: 'null'
        axisDim:
          anyOf:
            - $ref: '#/components/schemas/DimAxisOptions'
            - type: 'null'
      type: object
      title: ChartRenderOptions
      description: |-
        Options for rendering a chart from workbook data. Specify the data
        range, chart type, image output format, and title and axis labels.
    ReferenceObject:
      properties:
        cells:
          type: string
          title: Cells
          description: Unprefixed A1-style range, id, or name
          examples:
            - A1:B2
            - C32
            - name
        sheet:
          anyOf:
            - type: string
            - type: 'null'
          title: Sheet
          description: Name of the sheet to reference
          examples:
            - Sheet1
            - Loan Calculator
      type: object
      required:
        - cells
        - sheet
      title: ReferenceObject
      description: A reference to a range of spreadsheet cells.
    SupportedChartTypes:
      type: string
      enum:
        - area
        - bar
        - column
        - combo
        - line
        - pie
        - scatterplot
        - waterfall
      title: SupportedChartTypes
      description: Types of charts that can be rendered using workbook data.
    SupportedImageTypes:
      type: string
      enum:
        - png
        - svg
      title: SupportedImageTypes
      description: Supported image types for rendering charts from workbook data.
    SupportedValueLabelTypes:
      type: string
      enum:
        - none
        - selective
        - all
      title: SupportedValueLabelTypes
      description: |-
        Options for labelling individual data values on a chart. If "none" (the
        default) then no data labels are shown. If "selective", data labels are
        shown when they fit without overlap. If "all", all values are labelled.
    SupportedDirTypes:
      type: string
      enum:
        - ''
        - col
        - row
      title: SupportedDirTypes
      description: Enum representing the supported read orientations for data directions.
    SupportedBooleanTypes:
      type: string
      enum:
        - 'false'
        - 'true'
      title: SupportedBooleanTypes
    SupportedBlankTypes:
      type: string
      enum:
        - gap
        - zero
        - span
      title: SupportedBlankTypes
      description: |-
        Enum representing the supported strategies for handling blank or missing
        data points.
    SupportedInterpolationTypes:
      type: string
      enum:
        - linear
        - step
        - step-after
        - step-before
        - monotone
        - basis
      title: SupportedInterpolationTypes
      description: >-
        Enum representing the supported interpolation types for data
        visualization

        or curve fitting.
    SupportedSortDirections:
      type: string
      enum:
        - ''
        - ascending
        - descending
      title: SupportedSortDirections
    ValueAxisOptions:
      properties:
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
          description: Cell reference to use as the axis title. Can also be plain text.
          examples:
            - '=C4'
            - Price in ISK
        type:
          anyOf:
            - $ref: '#/components/schemas/SupportedAxisTypes'
            - type: 'null'
          description: The type of scale used by the axis.
          default: linear
        numberFormat:
          anyOf:
            - type: string
            - type: 'null'
          title: Numberformat
          description: Number format pattern used for formatting the axis labels.
          examples:
            - '#,##0.0'
            - 0.0%
        reverse:
          anyOf:
            - $ref: '#/components/schemas/SupportedBooleanTypes'
            - type: 'null'
          description: Draw the axis in ascending or descending order.
          default: 'false'
        min:
          anyOf:
            - type: number
            - type: 'null'
          title: Min
          description: A minimum value for the axis.
        max:
          anyOf:
            - type: number
            - type: 'null'
          title: Max
          description: A maximum value for the axis.
        clip:
          anyOf:
            - $ref: '#/components/schemas/SupportedBooleanTypes'
            - type: 'null'
          description: >-
            If true, any graphics outside the min or max boundaries of the axes
            are truncated.
          default: 'false'
      type: object
      title: ValueAxisOptions
      description: How an axis representing value magnitudes is presented.
    DimAxisOptions:
      properties:
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
          description: Cell reference to use as the axis title. Can also be plain text.
          examples:
            - '=C4'
            - Price in ISK
        numberFormat:
          anyOf:
            - type: string
            - type: 'null'
          title: Numberformat
          description: Number format pattern used for formatting the axis labels.
          examples:
            - '#,##0.0'
            - 0.0%
        reverse:
          anyOf:
            - $ref: '#/components/schemas/SupportedBooleanTypes'
            - type: 'null'
          description: >-
            If true, invert the scale of the axis. If false, keep the order
            untouched.
          default: 'false'
      type: object
      title: DimAxisOptions
      description: How an axis representing dimensional categories is presented.
    SupportedAxisTypes:
      type: string
      enum:
        - linear
        - log
      title: SupportedAxisTypes
      description: Types of scales that can be used by an axis.
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: JWT

````