Working with Tables

⚠️
Current limitations
The API currently only supports reading and replacing unstructured tables.
Support for structured tables and targeted edits is an area of active development.

Table rows are where most document lab data lives. Because row data can be large, you must access it independently from listing all document parts.

A few key properties about working with tables:

When listing a document's content, you only view table summary information.
To retrieve table detail information, such as row data, you need to query another endpoint.

Reading table data

When listing a document's content, you view table summary objects.

GET /api/v3/entry/etr_8rVKW0g7/parts/items

{
  "items": [
    ...,
    {
      "id": "docpart_XZuYFzO2t3",
      "versionId": "etrver_7yoe6Pzfd1",
      "modifiedAt": "2026-08-13T22:59:05.949663Z",
      "content": {
        "__typename": "UnstructuredTableDocumentContentSummary",
        "name": "Concentration Measurements",
        "indentation": 0,
        "columnDefinitions": [
          {
            "__typename": "TableColumnDefinition",
            "name": "Sample ID",
            "isLocked": false,
            "width": 100
          },
          {
            "__typename": "TableColumnDefinition",
            "name": "Concentration (ng/µL)",
            "isLocked": false,
            "width": 150
          }
        ],
        "rowCount": 3,
        "isEvaluated": false
      },
    },
    ...
  ],
  "nextToken": ""
}

To retrieve the table rows and other details about the table, make another request.

GET /api/v3/document-part-unstructured-table/docpart_XZuYFzO2t3

{
  "id": "docpart_XZuYFzO2t3",
  "versionId": "etrver_7yoe6Pzfd1",
  "content": {
    "__typename": "UnstructuredTableDocumentContent",
    "name": "Concentration Measurements",
    "columnDefinitions": [
      { "name": "Sample ID" },
      { "name": "Concentration (ng/µL)" }
    ],
    "rows": [
      {
        "cells": [
          { "inputValue": { "type": "text_value", "value": "SMPL_001" } },
          { "inputValue": { "type": "text_value", "value": "0.85" }, "evaluatedValue": { "type": "text_value", "value": "0.85" } }
        ]
      }
    ],
    "isEvaluated": true
  }
}

Cell values

When looking at cell data from tables, two properties represent the value of the cell.

The inputValue is the value editable by the user or API. It can always be of type text_value to include plain text, cell references, and formulas.
The evaluatedValue is the value the spreadsheet evaluator outputs. It usually matches what Benchling displays. Prefer this value when reading from the table, but it's not always available. To learn more, visit the Evaluation section.

Evaluation

Tables participate in spreadsheet evaluation. Evaluation takes the inputValues and coerces them into the standard values Benchling displays on tables. It is responsible for interpreting spreadsheet references and formulas (for example, =SUM(A1:A10)/6).

The isEvaluated property on the table indicates whether evaluatedValues are available on the cells.

Currently, only the browser client performs spreadsheet evaluation. The only way to generate new evaluatedValues is to edit the document in the Benchling web application. Any API edit clears the evaluated values until you edit the document in Benchling again.

Writing table data

To write table data, insert a new table with a partsMutation, or replace an existing table. In either case, provide the full specification of the desired table.

PATCH /api/v3/document-part-unstructured-table/{doc_part_id}

{
  "versionId": "etrver_YczTdvGdm6",
  "columnDefinitions": [
    { "name": "Sample ID" },
    { "name": "Value" }
  ],
  "rows": [
    {
      "cells": [
        {
          "inputValue": { "type": "text_value", "value": "SMPL_001" }
        },
        {
          "inputValue": { "type": "text_value", "value": "='DataTable'!A1 * 100" },
          "format": { "backgroundColor": "#FDC68A" }
        }
      ]
    },
    {
      "cells": [
        {
          "inputValue": { "type": "text_value", "value": "SMPL_002" },
          "format": { "link": "https://benchling.com/" }
        },
        {
          "inputValue": { "type": "text_value", "value": "124.600" }
        }
      ]
    }
  ]
}

Currently, we don't support making modular edits to a table such as row additions or targeted cell edits.