Skip to navigation

Uploading Results to Benchling through the API

Create assay results directly, transactionally, or in bulk into a Notebook results table.

Overview

This recipe creates qPCR results in a demo tenant with the V3 API and the V3 Python 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.

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.

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

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 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
The result schema settings page

JSON settings for the fields:

{
"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
Result table configuration in the UI

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 enabled):

The schema settings list with the Copy API ID option open on the qPCR row
Copy API ID on the row of the Schema Settings page

Our schema id is assaysch_FL4k8H51.

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

Create a result

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
Custom Entity with schema "qPCR Samples" named "Sample 1"

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

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.

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

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:

{
"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
Note: The "Reviewed" and "Source" fields are only applicable to results created in Notebook entries.

If you want to aggregate results across several entities or by other fields of the result, you can do so in our Insights product!

Update or archive a result

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

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.

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 for the full limits.

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

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:

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
The integrate icon in the results table toolbar

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.

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 to see how.

Or, check out more recipes for using the Developer Platform.