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

# Uploading Results to Benchling through the API

## Overview

This recipe creates qPCR results in a demo tenant with the [V3 API](/docs/v3-api-overview) and the [V3 Python SDK](/docs/getting-started-with-the-v3-sdk). It covers three ways to create results:

1. Create a single result.
2. Create up to 25 results in one all-or-nothing request with a batch create.
3. Create thousands of results asynchronously with a bulk create, optionally sending them to a results table in a Notebook entry.

You can also create results by processing an instrument output file in a Benchling Connect run, which is covered in [a separate recipe](/docs/use-apis-to-process-outputfile-with-lab-automation).

> **Info**
>
> The V3 result endpoints are beta. Set `early_access="true"` on the client, as in the examples below, or send the `EARLY-ACCESS: true` header on raw HTTP requests. See the [V3 Stability Guidelines](/docs/stability-guidelines).

Every example below uses this client. Pass your tenant's root URL; the SDK adds `/api/v3` itself.

```python
from benchling_v3_sdk import Benchling

benchling = Benchling(
    base_url="https://yourcompany.benchling.com",
    api_key="<your-api-key>",
    early_access="true",
)
```

## Create Result Schema

To create results in Benchling, there must first be a result schema that defines the structure of the results. Here is a [help article](https://help.benchling.com/hc/en-us/articles/9684271885581-Configure-a-Result-Table-with-JSON) that describes the process of creating a result schema in Benchling's UI. Please follow the article for help creating a result schema. We will use the following result schema for these examples, named "qPCR":

![The qPCR result schema settings page, listing the Sample ID, CT, CT Mean, Quantity, and Quantity Mean fields](/_fern-files/_img/17547501f939c0886c804a6447649ad4d70909c6ec950b8cbbabf9664b372d1e.webp)

JSON settings for the fields:

```json
{
    "fields": [
        {
            "displayName": "Sample ID",
            "name": "sample_id",
            "type": "entity_link",
            "isRequired": true,
            "isMulti": false
        },
        {
            "displayName": "CT",
            "name": "ct",
            "type": "float",
            "isRequired": true,
            "isMulti": false
        },
        {
            "displayName": "CT Mean",
            "name": "ct_mean",
            "type": "float",
            "isRequired": false,
            "isMulti": false
        },
        {
            "displayName": "Quantity",
            "name": "quantity",
            "type": "float",
            "isRequired": false,
            "isMulti": false
        },
        {
            "displayName": "Quantity Mean",
            "name": "quantity_mean",
            "type": "float",
            "isRequired": false,
            "isMulti": false
        }
    ]
}
```

Make sure to also configure your result table so all the columns will appear in the UI:

![The result table configuration screen with each schema field enabled as a column](/_fern-files/_img/11754257b2b0833d414658ec2f53c39b31f7d4f924ed46852d761ecf7a54168d.webp)

### Get Result Schema API ID

Once you have a result schema created, you can copy the API ID of that result schema from the result schema settings page (if you have the [copy API IDs setting](/docs/getting-started-1#copy-api-ids) enabled):

![The schema settings list with the Copy API ID option open on the qPCR row](/_fern-files/_img/1dd526bc4df8ba8ff5d52ddef4fc0e7e292f6881d568f39f7c59b8f290e76d3f.webp)

Our schema id is `assaysch_FL4k8H51`.

Now that we have our result schema created we can start creating results!

## Create a result \[#create-results]

This first example creates one result with `result.create`. To do this, we first need to know what we are logging the result against.

### Get Entity API ID

The result schema we have created has an Entity as the primary key field, meaning that they are meant to be logged against a specific entity. For our purposes, we'll use a simple custom entity as an example:

![A Benchling custom entity named Sample 1 with the qPCR Samples schema assigned](/_fern-files/_img/aa5cba94053f5e326e156d7e44b77c1c0e55c55bedb628afb7047170c1d9df89.webp)

Copy the API ID from the UI by right clicking, or look the entity up by name:

```python
sample = next(iter(benchling.custom_entity.list(name_any_of_case_sensitive="Sample 1")))
print(sample.id)
```

Our entity's ID is `bfi_ELstHqON`.

### Get Project ID

We will now choose the project to upload the result to. Typically you will want to choose the same project that the Entity is in from the previous step.

> **Warning**
>
> **Project ID is required**
>
> Only users with read access to the project *posted with the result* can see it, so pick the project whose members should see the data.

To retrieve the project ID, you can try a few different approaches:

1. Copy it from the UI by right clicking in the project menu and using the [Copy API ID option](/docs/getting-started-1#copy-api-ids).
2. Get the entity from the previous step and read its project: `benchling.custom_entity.get("bfi_ELstHqON").project.id`.
3. List projects with `benchling.project.list(...)` and pick the destination project.

Our destination project ID is `src_wMsnz0ru`.

### Create the result

Using the result schema ID (`assaysch_FL4k8H51`), entity ID (`bfi_ELstHqON`), and project ID (`src_wMsnz0ru`) that we recorded earlier, plus example values for CT, CT Mean, Quantity, and Quantity Mean, we can create the result. Each value is wrapped in a `FieldValueInput`, and fields are keyed by their `name`, not their `displayName`:

```python
from benchling_v3_sdk import FieldValueInput

result = benchling.result.create(
    schema_id="assaysch_FL4k8H51",
    project_id="src_wMsnz0ru",
    schema_fields={
        "sample_id": FieldValueInput(value="bfi_ELstHqON"),
        "ct": FieldValueInput(value=11.115),
        "ct_mean": FieldValueInput(value=11.142),
        "quantity": FieldValueInput(value=16.858),
        "quantity_mean": FieldValueInput(value=16.568),
    },
)
print(result.id)
```

The SDK sends this request body to `POST /api/v3/result`:

```json
{
  "schemaId": "assaysch_FL4k8H51",
  "projectId": "src_wMsnz0ru",
  "schemaFields": {
    "sample_id": {"value": "bfi_ELstHqON"},
    "ct": {"value": 11.115},
    "ct_mean": {"value": 11.142},
    "quantity": {"value": 16.858},
    "quantity_mean": {"value": 16.568}
  }
}
```

Once you've created the result, you can view it on the "Results" tab of the sample entity in the UI:

![The Results tab of a custom entity showing the newly created qPCR result row](/_fern-files/_img/11439049b659dbcc86ba6d06ebb7160613d27ce9c3da7d65476296a1a0ba4fc4.webp)

If you want to aggregate results across several entities or by other fields of the result, you can do so in our [Insights product](https://help.benchling.com/hc/en-us/articles/9684135542541-Insights-basics)!

### Update or archive a result

Results can be updated in place. Pass only the fields you want to change:

```python
benchling.result.update(
    result_id=result.id,
    schema_fields={"ct_mean": FieldValueInput(value=11.150)},
)
```

To retire a result instead, archive it with `archived=True` and an `archive_reason`.

## Create results together in a batch

Often you need several results to be created *transactionally*: either every result is created, or none are. `result.batch_create` does this synchronously in a single transaction, for up to 25 results per request. It replaces the V2 results transaction endpoints.

```python
from benchling_v3_sdk import CreateResultInput, FieldValueInput

rows = [
    ("bfi_ELstHqON", 11.115, 16.858),
    ("bfi_Xq2PmTzA", 12.034, 14.201),
]

response = benchling.result.batch_create(
    items=[
        CreateResultInput(
            schema_id="assaysch_FL4k8H51",
            project_id="src_wMsnz0ru",
            schema_fields={
                "sample_id": FieldValueInput(value=sample_id),
                "ct": FieldValueInput(value=ct),
                "quantity": FieldValueInput(value=quantity),
            },
        )
        for sample_id, ct, quantity in rows
    ]
)
print([created.id for created in response.items])
```

If any result in the batch fails validation, the request fails and no results are created. For more than 25 results, use a bulk create.

## Create results in bulk

`result.bulk_create` creates results asynchronously from a JSONL scratch file, one result per line. Each line has a `request_id` you choose and an `input_object` in the same shape as the `POST /api/v3/result` body. A bulk create accepts up to 30,000 objects or 100 MB; see [Bulk Import](/docs/bulk-import) for the full limits.

```python
import json

rows = [
    ("bfi_ELstHqON", 11.115, 16.858),
    ("bfi_Xq2PmTzA", 12.034, 14.201),
]

lines = [
    {
        "request_id": str(index),
        "input_object": {
            "schemaId": "assaysch_FL4k8H51",
            "projectId": "src_wMsnz0ru",
            "schemaFields": {
                "sample_id": {"value": sample_id},
                "ct": {"value": ct},
                "quantity": {"value": quantity},
            },
        },
    }
    for index, (sample_id, ct, quantity) in enumerate(rows)
]

scratch_file = benchling.scratch_file.create_and_upload(
    contents="\n".join(json.dumps(line) for line in lines) + "\n",
    filename="qpcr-results.jsonl",
)

link = benchling.result.bulk_create(file_id=scratch_file.id)
completion = benchling.wait_for_task_completion(link)

if completion.success:
    print("Every result was created")
elif completion.partial:
    print("Some results failed:", completion.message)
else:
    print("The task failed:", completion.message)
```

Unlike a batch, a bulk create is not all-or-nothing: a finished task can report item-level failures, so check the completion as shown. [Waiting on tasks](/docs/common-sdk-interactions-and-examples-v3#bulk-operations) in the V3 SDK guide explains the task states.

## Create results for a specific table in the Notebook

Another common use case is sending results to an existing results table in a Notebook entry. Add the table's document part ID to each result, as `document_part_results_table_id` in the SDK or `documentPartResultsTableId` in a bulk file.

### Find the table's document part ID

First add a results table with the proper result schema to a Notebook entry, either in Benchling or with the API as shown in [Creating a new Notebook Entry containing Results](/docs/creating-a-new-notebook-entry-containing-results). Make sure the user or app submitting the results has read and write access to the entry.

You can find the entry ID near the end of the entry's URL, put together with the entry's name. The end of the URL should look like `/etr_abcd1234-my-entry/edit`; in that example, the name of the entry is "My Entry", and the API ID is `etr_abcd1234`.

List the entry's parts and pick out the results tables. Parts are returned in the order they appear in the entry, so if the entry has several results tables, use their position to choose:

```python
results_tables = [
    part
    for part in benchling.entry.list_parts(entry_id="etr_abcd1234")
    if part.typename == "DocumentPartResultsTable"
]
table_id = results_tables[0].id  # looks like docpart_aBCdEfgh
```

### Create the results

Pass the table's ID alongside the other fields:

```python
benchling.result.create(
    schema_id="assaysch_FL4k8H51",
    project_id="src_wMsnz0ru",
    document_part_results_table_id=table_id,
    schema_fields={
        "sample_id": FieldValueInput(value="bfi_ELstHqON"),
        "ct": FieldValueInput(value=11.115),
    },
)
```

The same argument works on each `CreateResultInput` in a batch, and as `documentPartResultsTableId` in each `input_object` of a bulk file.

### Integrating the Results into the Table

![A Notebook results table toolbar with the plug icon that appends pending results into the table](/_fern-files/_img/1538e7e8972ff67cf1f4e06d1d478308906a2a6fdf9330753bc0dcdae79952ff.webp)

When results are created in this way, they are not immediately appended to the destination table. Their source is marked as "pending" and they will not appear in the table until they are explicitly integrated. To integrate pending results into a table, click the plug icon in the toolbar of the table, and any pending results will be appended to the bottom of the table, replacing any blank trailing rows. Hovering over the icon without clicking will display a tooltip with the number of pending rows.

Notebook tables have a maximum number of rows. Pending results can't be integrated if doing so would push the table past that maximum, so split a large set of results across more than one table.

Note that if you had the entry open while you submitted the results with the API, you may need to refresh the page for the table to detect the newly pending results.

## Next Steps

For more information on results, check out how you can visualize results using our Insights product or how you can upload files containing results via Benchling Connect through our articles on [help.benchling.com](https://help.benchling.com/).

If you created results without attaching them directly to a table in the notebook, you can still visualize the results created via API in a Notebook Entry. Use this help article on [lookup tables and columns](https://help.benchling.com/hc/en-us/articles/9684194769421-Lookup-Columns-and-Tables) to see how.

Or, check out [more recipes](/docs/recipes) for using the Developer Platform.