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

# Analyses API Developer Guide

The Analyses API includes a number of endpoints for working with the Benchling Analysis
product. Integrators can use the import/export functionality of Benchling analyses to
let users interact with external systems, pulling Benchling data out for external
analysis and uploading post-analysis data files back in.

This guide walks through how Benchling users interact with the Analyses product, and
how apps can extend an analysis through import/export. That includes the Analyses API
endpoints in more detail, as well as core concepts such as analysis keys. Like most
integrations, we recommend Analysis integrations use app authentication, so before
working with the Analyses API make sure you're familiar with building
[Benchling Apps](/docs/getting-started-benchling-apps).

> **Info**
>
> ### This page uses V2 because the analysis write path is V2-only
>
> [V3](/docs/v3-api-overview) is the recommended API for new development, and it does expose analyses (`GET /api/v3/analysis/items`, `GET /api/v3/analysis/{analysis_id}`, `GET /api/v3/data-frame/items`, and the analysis template endpoints), but all of them are read-only. Patching an analysis and creating a data frame have no V3 equivalent, and the import/export flow below depends on both, so it stays on V2 end to end.
>
> Use the V3 endpoints when you only need to read an analysis, its steps, or its data frames.

## Getting started

Before diving in, it's worth a closer look at how Benchling users create analyses to
process their data. Benchling analyses include:

* **Analysis object.** Objects that let users view and analyze experimental result
  data
* **Data frames.** Tabular data used in analyses
* **Files.** Raw files (images, text, HTML)

Apps interact with analyses through the **import/export** feature, which lets an
integration both **export data frames** from Benchling and **import data frames and
files** into Benchling. To users, this all happens as part of a single action in their
Benchling Analysis.

## Analysis integration user flow

Users interact with import/export in the following way. First, a user copies the
[analysis key](#analysis-key) from the import/export dialog in Benchling. Next, they
provide the key to the integration through an external UI. Finally, the user returns to
the Benchling Analysis, where the external system has sent the data frame.

While the purpose of an Analysis integration is to process or analyze data on an
external platform, the following components are also crucial:

* A UI for accepting an analysis key
* A mechanism for pulling data frames from Benchling
* A mechanism for pushing data frames and files to Benchling

## Analysis key

An analysis key is a value provided to Benchling users when working with the
import/export feature. It is composed of the relevant `analysis_id` and a JSON Web
Token (JWT), separated by a colon (`:`). The `analysis_id` is the internal Benchling
identifier for the analysis, and the JWT can be used to authenticate requests to the
customer's tenant.

Here's an example key:

```
ana_ABCD1234:eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
```

The JWTs associated with analysis keys expire after **10 minutes**, after which users
must generate a new one. A new key is generated each time a Benchling user copies one
from the import/export dialog, so if you're using the key to authenticate, be sure to
prompt for a new key each time a user runs the external analysis.

> **Warning**
>
> While analysis keys include a JWT that can be used to authenticate requests, this is
> **not** a best practice. Analysis key authentication is fine for testing, but the
> 10-minute expiration makes it unsuitable for production applications. Consider
> creating a [Benchling App](/docs/getting-started-benchling-apps) and using app
> authentication instead.

The JWT payload portion of an analysis key contains information about the customer's
tenant, including a unique tenant identifier. This matters particularly when building
multi-tenant apps. Here's a Python example of working with analysis keys:

```python
# Separate the analysis_id value from the JWT
analysis_id, key = analysis_key.split(":")
# Split the JWT into its constituent parts
_headers, payload, _signature = key.split(".")
# Decode the JWT payload
jwt_payload = json.loads(base64.b64decode(f"{payload}=="))
tenant = jwt_payload["aud"]
```

## Downloading data frames from Benchling

Users start an analysis by creating an initial data frame from registry data, from a
dashboard query, or from existing tabular data. The
[Benchling Help Center](https://help.benchling.com/hc/en-us) has more on how users
interact with the
[Registry](https://help.benchling.com/hc/en-us/articles/9684259067917-What-is-the-Registry-)
and
[Insights](https://help.benchling.com/hc/en-us/articles/9684135542541-Insights-basics)
tools.

This initial data frame is the foundation of the analysis, and the starting point for
creating views and importing or exporting other files and data frames. Data frames are
the main object analyses work with, and an analysis can work with multiple data frames
at once.

![A Benchling Analysis showing an initial data frame of tabular assay data](/_fern-files/_img/5c87dddab2c0826449fa3537f98073f4f464f5774473c846f33941ec4be07dfb.webp)

Imports and exports begin with obtaining the relevant inputs. The Get an analysis
endpoint (`GET /v2-beta/analyses/:analysis_id`) returns an analysis object:

```json
{
  "id": "ana_DjEC6xL4",
  "dataframesIds": [
    "dset_t69ysPGQUl4H"
  ],
  "fileIds": [
    "file_UoqJSDwI"
  ],
  "folderId": "lib_Gfjd3i1m"
}
```

Note that there may be multiple data frames and files returned, since each analysis can have
any number of them to download.

### Data frame inputs

With a data frame ID from the `dataframesIds` array, query the Get a data frame
endpoint (`GET /v2/data-frames/:dataframes_id`) for the data frame's metadata. Two
fields matter most:

* `uploadStatus`: the current status of the data frame, one of `IN_PROGRESS`,
  `SUCCEEDED`, `FAILED_VALIDATION`, or `NOT_UPLOADED`. For the purposes of getting an
  initial data frame, we're only concerned with `SUCCEEDED`.
* `manifest`: a list of the files that make up the data frame, each represented by an
  object including the name and URL. The value of the `url` field varies with the data
  frame's `uploadStatus`:
  * For `SUCCEEDED` data frames, it is the file's download URL.
  * For `NOT_UPLOADED` data frames, it is a pre-signed URL used to upload a file via
    the Update a data frame endpoint (`PATCH /v2-beta/data-frames/{dataframes_id}`).
  * For all other statuses, `url` is `null`.

For data frames with an `uploadStatus` of `SUCCEEDED`, the `url` fields are pre-signed
URLs that can be used to download the data frame CSV data. Here's an example data
frame:

```csv
sample,ct,ct_mean,quantity,quantity_mean
qPCR Sample 15,17.453,17.419,0.245,0.251
qPCR Sample 14,17.364,17.257,0.26,0.28
qPCR Sample 13,16.481,16.43,0.469,0.486
qPCR Sample 12,30.507,30.345,0.01,0.011
qPCR Sample 11,30.072,30.345,0.01,0.011
qPCR Sample 10,30.456,30.345,0.01,0.011
qPCR Sample 9,22.175,22.144,0.01,0.011
qPCR Sample 8,22.106,22.144,0.011,0.011
qPCR Sample 7,22.152,22.144,0.011,0.011
qPCR Sample 6,17.316,17.306,0.269,0.271
qPCR Sample 1,11.115,11.142,16.858,16.568
```

### File inputs

Like data frame inputs, use the file IDs from the `fileIds` array to query the Get a
file endpoint (`GET /v2/files/{file_id}`) for metadata about the file:

```json
{
  "errorMessage": null,
  "uploadStatus": "SUCCEEDED",
  "id": "file_Of5GuBSq",
  "name": "IC50Chart",
  "filename": "IC50Chart.png",
  "folderId": "lib_Gfjd3i1m"
}
```

Unlike data frame inputs, the response doesn't contain a `manifest` field. Instead, a
`Content-Location` header includes the pre-signed URL where the file can be downloaded.

## Uploading data frames and files to a Benchling Analysis

Once an integration has completed an external analysis, the final product is uploaded
back to the Benchling Analysis. Both data frames (for tabular data) and files (for
images or other file types) can be pushed back.

Pushing data back involves creating the data frame or file definition in Benchling, then
uploading the relevant data to it.

> **Info**
>
> ### Files must live in a folder
>
> Files are first-class objects in Benchling, and therefore require a location when
> they are created, which is what the required `folderId` parameter supplies. Usually, files are
> created in the same folder as the associated analysis. The
> [Folders API](/docs/api/v2/benchling-api/folders) has more on folders in
> Benchling.

### Importing new data frames to a Benchling Analysis

Create data frames using the Create a data frame endpoint (`POST /v2/data-frames`),
first specifying the data frame's `manifest`, including the name of the data frame or
the file to be uploaded:

```json
{
  "manifest": [
    {
      "fileName": "09-14-2022_011620_PM_well_plate-part-00000.csv"
    }
  ],
  "name": "09-14-2022 01:16:20 PM well plate"
}
```

The response includes a complete data frame object with a status of `NOT_UPLOADED`; the
`manifest` now includes a pre-signed URL, and the object has a data frame ID:

```json
{
  "errorMessage": null,
  "id": "dset_LlDFupKyErxx",
  "manifest": [
    {
      "fileName": "09-14-2022_011620_PM_well_plate-part-00000.csv",
      "url": "https://benchling-location.s3.amazonaws.com/deploys/location/data_frames/source_files/.../09-14-2022_011620_PM_well_plate-part-00000.csv?..."
    }
  ],
  "name": "09-14-2022 01:16:20 PM well plate",
  "uploadStatus": "NOT_UPLOADED"
}
```

Using the `url`, upload the CSV to Benchling. Include the
`x-amz-server-side-encryption: AES256` header to work with Benchling's server-side
encryption:

```bash
curl -H "x-amz-server-side-encryption: AES256" -X PUT -T <LOCAL_FILE> -L <S3_PUT_URL>
```

Finally, update the status of the data frame to `IN_PROGRESS` using the data frame ID
and the Update a data frame endpoint (`PATCH /v2/data-frames/{dataframes_id}`):

```json
{
  "uploadStatus": "IN_PROGRESS"
}
```

This endpoint is asynchronous; a successful request returns a 202 Accepted with an
empty response body and launches the process to validate and transform the uploaded CSV
into a data frame. Once complete, the data frame's status is automatically updated to
`SUCCEEDED` or `FAILED_VALIDATION`.

### Importing new files to a Benchling Analysis

File imports follow a nearly identical process, with a couple of differences. First,
create a file definition in Benchling using the Create a file endpoint
(`POST /v2/files`):

```json
{
  "name": "IC50Chart",
  "filename": "IC50Chart.png",
  "folderId": "lib_Gfjd3i1m"
}
```

This creates the file definition, and as with data frames a file ID and pre-signed URL
are returned:

```json
{
  "errorMessage": null,
  "id": "file_Of5GuBSq",
  "name": "IC50Chart",
  "filename": "IC50Chart.png",
  "folderId": "lib_Gfjd3i1m",
  "uploadStatus": "NOT_UPLOADED"
}
```

Notably, the upload URL is *not* included in the response body. It is in the
`Content-Location` header instead. Upload the file to that URL, again including the
`x-amz-server-side-encryption: AES256` header:

```bash
curl -H "x-amz-server-side-encryption: AES256" -X PUT -T <LOCAL_FILE> -L <S3_PUT_URL>
```

Finally, update the status of the file definition. Unlike data frames, files undergo no
validation or conversion, so the status can be set directly to `SUCCEEDED`:

```json
{
  "uploadStatus": "SUCCEEDED",
  "folderId": "lib_Gfjd3i1m"
}
```

Benchling supports a maximum file size of 30 MB. Currently supported file types are
`.html`, `.jmp`, `.jrn`, `.jrp`, `.jpeg`, `.jpg`, `.png`, `.csv`, and `.txt`.

## End-to-end example

Here is the file and data frame upload process in Python:

```python
import json
import os
import requests

# Calls should be authenticated using the app's OAuth access token
token = os.environ["TOKEN"]
tenant = "my.benchling.com"

# For file uploads:
filename = "myfile.txt"
name = "My File"

# Create the file definition in Benchling
file_post = requests.post(
    f"https://{tenant}/api/v2/files",
    data=json.dumps({"filename": filename, "folderId": "lib_lOAKZhDQ", "name": name}),
    headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
)

# Store the upload URL and file_id
file_post_resp = json.loads(file_post.content)
bench_put_url = file_post.headers["Content-Location"]
file_id = file_post_resp["id"]

# Upload the file contents to Benchling
bench_put = requests.put(
    bench_put_url,
    data=open(filename, "rb"),
    headers={"x-amz-server-side-encryption": "AES256"},
)

# Update the file object in Benchling to indicate success
file_patch = requests.patch(
    f"https://{tenant}/api/v2/files/{file_id}",
    data=json.dumps({"uploadStatus": "SUCCEEDED"}),
    headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
)

# For data frame uploads:
filename = "mydataframe.csv"
dataframe_name = "My Data Frame"

# Create the data frame definition in Benchling
dataframe_post = requests.post(
    f"https://{tenant}/api/v2/data-frames",
    data=json.dumps({"manifest": [{"fileName": filename}], "name": dataframe_name}),
    headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
)

# Store the upload URL and dataframe_id
dataframe_post_resp = json.loads(dataframe_post.content)
bench_put_url = dataframe_post_resp["manifest"][0]["url"]
dataframe_id = dataframe_post_resp["id"]

# Upload the data frame file to Benchling
bench_put = requests.put(
    bench_put_url,
    data=open(filename, "rb"),
    headers={"x-amz-server-side-encryption": "AES256"},
)

# Update the data frame object in Benchling to begin processing
dataframe_patch = requests.patch(
    f"https://{tenant}/api/v2/data-frames/{dataframe_id}",
    data=json.dumps({"uploadStatus": "IN_PROGRESS"}),
    headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
)
```

## Associating data frames and files to an analysis

Once data frames or files from an external analysis have been uploaded to Benchling,
they can be attached to the analysis. This means updating the analysis to include them
using the Update an analysis endpoint (`PATCH /v2-beta/analyses/{analysis_id}`).
Additional requests with data frames or files *append* the new objects to the analysis.

Attaching a data frame:

```json
{
  "dataframesIds": [
    "dset_LlDFupKyErxx"
  ]
}
```

The same request in Python:

```python
patch_data = requests.patch(
    f"https://{tenant}/api/v2-beta/analyses/{analysis_id}",
    data=json.dumps({"outputData": {"dataframesIds": ["dset_LlDFupKyErxx"]}}),
    headers={"Authorization": f"Bearer {token}"},
)
```