Benchling

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 will be covered in a 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":

Screenshot of the result schema settings pageScreenshot of the result schema settings page

Screenshot of 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:

Result Table Config UIResult Table Config UI

Result Table Config 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):

Copy API ID on the row of the Schema Settings pageCopy API ID on the row of the Schema Settings page

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

Custom Entity with schema "qPCR Samples" named "Sample 1"Custom Entity with schema "qPCR Samples" named "Sample 1"

Custom Entity with schema "qPCR Samples" named "Sample 1"

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 and filtering by name.

Our entity's ID is bfi_ELstHqON.

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, id, and projectId are not required, so we will omit them for simplicity.

Note: Always use the reference docs, not this screenshot, for the latest informationNote: Always use the reference docs, not this screenshot, for the latest information

Note: Always use the reference docs, not this screenshot, for the latest information

Using the result schema ID (assaysch_FL4k8H51) and entity ID (bfi_ELstHqON) 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"
    }
  ]
}

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:

Note: The "Reviewed" and "Source" fields are only applicable to results created in Notebook entries.Note: The "Reviewed" and "Source" fields are only applicable to results created in Notebook entries.

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!

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.

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

Updated 2 days ago

Uploading Results to Benchling through the API


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.