> This page is for Developer Documentation.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.benchling.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.benchling.com/_mcp/server.

# Working with Tables

> **Info**
>
> ### Beta APIs
>
> The Document APIs are beta. Send the `EARLY-ACCESS: true` header on every request shown here; without it these endpoints are unavailable. See [Introduction to Documents](/docs/introduction-to-documents) and the [Stability Guidelines](/docs/stability-guidelines).

> **Warning**
>
> ### Current limitations
>
> The API reads and writes data in unstructured tables and Results tables. Support for more structured table types is in active development.

Table rows are where most document lab data lives. Because row data can be large, it is fetched separately from the list of document parts.

Documents contain two kinds of tables:

* **Unstructured tables** have free-form columns, and every cell holds text.
* **Structured tables** have columns defined by a schema, and each cell holds a value of its column's type. The supported structured table type is the **Results table**.

## Reading table data

When you list a document's content, tables appear as summary objects. The `__typename` identifies the kind of table, such as `DocumentPartUnstructuredTable` or `DocumentPartResultsTable`.

**`Endpoint`**

```text title="Endpoint"
GET /api/v3/entry/etr_8rVKW0g7/parts/items
```

To get the table's columns and other details, request the table by ID.

**`Endpoint`**

```text title="Endpoint"
GET /api/v3/document-part-results-table/docpart_2mWG2SPvHX
```

**`Example Response`**

```json title="Example Response"
{
  "id": "docpart_2mWG2SPvHX",
  "name": "Titer Results",
  "columnDefinitions": [
    {
      "name": "Sample",
      "cellValueType": "ENTITY_LINK",
      "isRequired": true,
      "isReadonly": false,
      "isLocked": false,
      "isArchived": false,
      "allowsArrayValues": false,
      "width": 200,
      "columnId": "123c2f42-fbc4-4d02-b12d-b1d3cfd622bb",
      "fieldDefinitionApiId": "tsf_GZyEcevzIo",
      "__typename": "SchemaFieldColumnDefinition"
    },
    {
      "name": "Titer (mg/L)",
      "cellValueType": "DECIMAL",
      ...
    }
  ],
  "resultSchema": { "id": "assaysch_IdqoNLh6SG" },
  "rowCount": 10,
  "rows": "https://example.benchling.com/api/v3/document-part-results-table/docpart_2mWG2SPvHX/rows/items",
  "isEvaluated": false,
  "isSubmittable": false,
  "submissionStatus": "UNSUBMITTED",
  "versionMetadata": {
    "versionId": "etrver_4tSNBOhFN0",
    "createdAt": "2026-10-05T09:47:31.768440Z"
  },
  "__typename": "DocumentPartResultsTable"
}
```

On structured tables, each column definition has a `cellValueType`, which sets the type of value the column accepts.

To get the rows, follow the `rows` URL. Rows are paginated with `pageSize` and `nextToken`.

**`Endpoint`**

```text title="Endpoint"
GET /api/v3/document-part-results-table/docpart_2mWG2SPvHX/rows/items
```

**`Example Response`**

```json title="Example Response"
{
  "items": [
    {
      "id": "strow_2mWG2SPvHX:440a4b32-68be-4529-941b-046baa602b1f",
      "rowId": "440a4b32-68be-4529-941b-046baa602b1f",
      "rowIndex": 0,
      "isArchived": false,
      "isSubmittable": false,
      "submissionStatus": "UNSUBMITTED",
      "result": null,
      "documentPart": { "id": "docpart_2mWG2SPvHX", "__typename": "DocumentPartResultsTable" },
      "cells": [
        {
          "inputValue": {
            "value": { "id": "seq_GY9TBGyE12", "__typename": "DnaSequence" },
            "__typename": "ObjectLinkValue"
          },
          "evaluationValue": {
            "id": "seq_GY9TBGyE12",
            "name": "pTG-GFP-01",
            "__typename": "ObjectLinkCellEvaluationValue"
          },
          "errors": [],
          "format": null,
          "mergeRange": null,
          "mergeRangeParent": null,
          "__typename": "StructuredTableCell"
        },
        ...
      ],
      "__typename": "StructuredTableRow"
    },
    ...
  ],
  "nextToken": ""
}
```

### Cell values

Two properties hold a cell's value:

* **`inputValue`** is the value the user or API edits. In unstructured tables it's always a `TextValue`, which can hold plain text, cell references, and formulas. In structured tables its type matches the column, such as `ObjectLinkValue` or `DecimalValue`.
* **`evaluationValue`** is what the spreadsheet evaluator outputs, and it usually matches what Benchling displays. Prefer it when reading a table, but it isn't always available; see [Evaluation](#evaluation).

### Evaluation

Tables take part in spreadsheet evaluation. Evaluation takes each `inputValue` and coerces it into the standard value Benchling displays. It's also what interprets spreadsheet references and formulas, such as `=SUM(A1:A10)/6`.

The table's `isEvaluated` property says whether its cells have `evaluationValue`s.

Only the browser client evaluates spreadsheets. New `evaluationValue`s are generated only when someone edits the document in the Benchling web app. Any API edit clears the evaluated values until the document is next edited there. When you read a table right after an API write, fall back to `inputValue` if `evaluationValue` is null.

## Writing table data

Tables are edited with a `partsMutation` on the document that contains them. The request body is the same for unstructured and structured tables.

**`Endpoint`**

```text title="Endpoint"
PATCH /api/v3/entry/{entry_id}
```

Two operations edit an existing table:

* **`insert_table_rows`** adds rows to the end of a table.
* **`update_table_cells`** changes the value or formatting of specific cells.

Every `partsMutation` needs the document's current `version`. It's available as `versionMetadata.versionId` on the document or on any of its parts. If it doesn't match the current version on the server, the request returns HTTP `409`. Get the latest version and retry.

### Inserting rows

Each new row lists the cells to fill in, and each cell targets a column by `columnIndex`. Columns without a cell get the column's default value, and default formulas shift down to the new row.

**`Example Request`**

```json title="Example Request"
{
  "partsMutation": {
    "operationType": "insert_table_rows",
    "version": "etrver_4tSNBOhFN0",
    "documentPartId": "docpart_2mWG2SPvHX",
    "rows": [
      {
        "cells": [
          { "columnIndex": 0, "inputValue": { "type": "object_link_value", "id": "seq_GY9TBGyE12" } },
          { "columnIndex": 1, "inputValue": { "type": "decimal_value", "value": "412.5" } }
        ]
      },
      {
        "cells": [
          { "columnIndex": 0, "inputValue": { "type": "object_link_value", "id": "seq_EgpEP0tiai" } },
          {
            "columnIndex": 1,
            "inputValue": { "type": "decimal_value", "value": "88.0" },
            "format": { "backgroundColor": "#F8B4B4" }
          }
        ]
      }
    ]
  }
}
```

Two optional properties control where the rows go:

* **`position`** sets where the rows are inserted. The only supported value is `end_of_table`, which is the default.
* **`replaceEmptyTrailingRows`**, when `true`, replaces any empty rows at the end of the table with the new rows, instead of inserting after them. A row is empty when it's unsubmitted and every cell matches its column's default value. This helps with templates that start with blank rows. Defaults to `false`.

To find a column's `columnIndex`, look the column up by name in the table's `columnDefinitions`. Matching by name keeps an integration working if the columns are reordered.

### Updating cells

Each cell update targets one cell by `rowIndex` and `columnIndex`, both counted from 0. In each update:

* **`inputValue`:** include it to change the value, set it to `null` to clear the value, or leave it out to keep the existing value.
* **`format`:** include it to change the cell's formatting.

This example changes one value, and highlights another cell without changing its value.

**`Example Request`**

```json title="Example Request"
{
  "partsMutation": {
    "operationType": "update_table_cells",
    "version": "etrver_9KdQ2mVbXe",
    "documentPartId": "docpart_2mWG2SPvHX",
    "cellUpdates": [
      {
        "rowIndex": 3,
        "columnIndex": 1,
        "inputValue": { "type": "decimal_value", "value": "405.0" }
      },
      {
        "rowIndex": 3,
        "columnIndex": 0,
        "format": { "backgroundColor": "#FDC68A" }
      }
    ]
  }
}
```

### Cell value types

Unstructured table cells always take a `text_value`. Structured table cells take the type that matches the column's `cellValueType`, or a `text_value` holding a formula.

| Type                     | Shape                                                           | Notes                                           |
| ------------------------ | --------------------------------------------------------------- | ----------------------------------------------- |
| `text_value`             | `{ "type": "text_value", "value": "..." }`                      |                                                 |
| `integer_value`          | `{ "type": "integer_value", "value": 882 }`                     |                                                 |
| `decimal_value`          | `{ "type": "decimal_value", "value": "99.5" }`                  | `value` is a string, to preserve precision.     |
| `boolean_value`          | `{ "type": "boolean_value", "value": true }`                    |                                                 |
| `date_value`             | `{ "type": "date_value", "value": "2026-10-05" }`               |                                                 |
| `datetime_value`         | `{ "type": "datetime_value", "value": "2026-10-05T22:34:00Z" }` | Expects UTC.                                    |
| `object_link_value`      | `{ "type": "object_link_value", "id": "seq_GY9TBGyE12" }`       | Links to one Benchling item, such as an entity. |
| `object_link_list_value` | `{ "type": "object_link_list_value", "ids": ["...", "..."] }`   | Links to several Benchling items.               |