Uploading Results to Benchling through the API
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:
- Create a single result.
- Create up to 25 results in one all-or-nothing request with a batch create.
- 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.
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”:

JSON settings for the fields:
Make sure to also configure your result table so all the columns will appear 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):

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:

Copy the API ID from the UI by right clicking, or look the entity up by name:
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:
- Copy it from the UI by right clicking in the project menu and using the Copy API ID option.
- Get the entity from the previous step and read its project:
benchling.custom_entity.get("bfi_ELstHqON").project.id. - 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:
The SDK sends this request body to POST /api/v3/result:
Once you’ve created the result, you can view it on the “Results” tab of the sample entity in the UI:

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:
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.
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.
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:
Create the results
Pass the table’s ID alongside the other fields:
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

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.