Uploading Results to Benchling through the API

Overview

The following example creates results in a demo environment.

There are 3 primary ways to create runs via the API:

1. Create results
2. Create results with a results transaction
3. Upload a csv file with results to a Lab Automation Run and process them

This guide will cover 1 & 2, while 3 requires Lab Auto and is covered in this separate doc! Note that this doesn't cover all the ways to create results in Benchling, but only covers what's possible through the API.

This example will leverage our interactive API documentation, so make sure you've gone through the Tutorial before proceeding.

📘

Current Gaps

There are a few gaps in the API interactions for results that are common requests. We are working on closing these gaps, but want to make users aware in the mean time:

1. Result tables in Notebook entries and their associated results cannot be created, updated, or archived via the API
2. Results cannot be updated through the API. They must be archived and new ones must be created.

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:

{
    "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:

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

This first example will be to create results directly in a single call through our API. We'll be using the POST /assay-results endpoint. To do this, we first must know what we are logging results 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:

Again, I can get the API ID from the UI by right clicking and copying it, or by searching for it in the API by using the GET /custom-entities endpoint (or whatever endpoint is appropriate for its schema type) and filtering 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 should almost always be included

Only users with read access to the projectId posted with the result will be able to see the assay result.

Leaving project ID empty will result in only the creator of the result having read access.

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. Using the entity ID from the previous step:
   a. GET it using that ID from the API.
   b. Extract up entity's folderId from the returned resource.
   c. GET the folder from the API.
   d. Extract the projectId field from the returned resource.
3. List projects using the available filters to find the desired destination project and extracting the id field from the returned resource.

Our desired destination project ID is src_wMsnz0ru.

Create JSON Results

Looking at the example JSON for the create-results endpoint, we have to fill out the following structure:

{
  "assayResults": [
    {
      "fieldValidation": {
        "additionalProp1": {
          "validationComment": "string",
          "validationStatus": "VALID"
        },
        "additionalProp2": {
          "validationComment": "string",
          "validationStatus": "VALID"
        },
        "additionalProp3": {
          "validationComment": "string",
          "validationStatus": "VALID"
        }
      },
      "fields": {},
      "id": "string",
      "projectId": "string",
      "schemaId": "string"
    }
  ]
}

From the schema view, we can see that fieldValidation and id fields are not required, so we will omit them for simplicity. It also indicates that projectId is not required, but since we know we want others to be able to view these results, we must include it.

Using the result schema ID (assaysch_FL4k8H51), entity ID (bfi_ELstHqON), and project ID (src_wMsnz0ru) that we recorded earlier, as well as these example values for CT, CT Mean, Quantity, and Quantity Mean respectively: 11.115, 11.142, 16.858, 16.568. We can fill out the JSON body of the request! Remember, you must use the name of the field to reference it, not the displayName.

{
  "assayResults": [
    {
      "fields": {
        "sample_id": {"value": "bfi_ELstHqON"},
        "ct": {"value": 11.115},
        "ct_mean": {"value": 11.142},
    		"quantity": {"value": 16.858},
    		"quantity_mean": {"value": 16.568}
    	},
      "schemaId": "assaysch_FL4k8H51",
      "projectId": "src_wMsnz0ru"
    }
  ]
}

You can click on 'Test API' button and post this JSON into the request body (directly in the documentation):

And hit "Execute"! If it goes through successfully, you should get the following response:

{
  "assayResults": [
    "23f5970d-3d05-4779-8418-a070937fe264"
  ],
  "errors": null
}

Once you've uploaded the result, you can view 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!

Create Results with a Results Transaction

Often times there is a need to create a large amount of results transactionally. This essentially means ensuring all results are either created successfully or fail together.

Creating these results follows the same process as outlined in the above section, but with additional steps to start and commit the transaction. In the above example, instead of directly using the POST /assay-results endpoint, you'll do the following:

1. Create a transaction and retrieve the transaction ID
2. Create results in the transaction using the transaction ID in the URL. This call can be repeated to add all the necessary results. Note: The structure of the results created in a transaction is exactly the same as the results created directly.
3. Commit the results transaction using the transaction ID.

If the commit fails, is aborted, or if a result fails to be created, all results submitted in the transaction fail as well.

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 Lab Automation through our articles on help.benchling.com.

To visualise the results created via API in a Notebook Entry, use this help article on [lookup tables and columns] (https://help.benchling.com/en/articles/5611107-lookup-columns-and-tables)

Or, check out more examples for using the Developer Platform here on docs.benchling.com.