> 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. # Get a data frame GET https://{tenant_name}.benchling.com/api/v2/data-frames/{data_frame_id} Get a data frame and URLs to download its data. If the data frame has `SUCCEEDED` status, the `manifest` field in the response will contain URLs to each part of a data frame that can be downloaded and the names of the files. If the data frame has `NOT_UPLOADED` status, the `manifest` field in the response will contain S3 `PUT` URLs to upload data frame `.csv` files. See [Create a data frame](#/Data%20Frames/createDataFrames) for documentation of the full upload flow. If the data frame has `FAILED_VALIDATION` or `IN_PROGRESS` status, the `manifest` field in the response will only contain the names of the files and urls will be `null`. Notes: - Using this endpoint with `rowDataFormat=csv` might be slow and timeout on large data frames. We suggest using `rowDataFormat=parquet` for large data frames. - Parquet files contain column system names, which are unique column identifiers within the data frame and may be different from the column display names. The `columns` part of the response provides the display name and corresponding system name for each column. - CSV files contain column display names. - Manifest URLs are valid for 1 hour after being returned from this endpoint. They should not be stored persistently for later use. Reference: https://docs.benchling.com/docs/api/v2/benchling-api/data-frames/get-data-frame ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Request ### Path parameters - `data_frame_id` (string, required) — The ID of the data frame ### Query parameters - `returning` (string, optional) — Comma-separated list of fields to return. Modifies the output shape. To return all keys at a given level, enumerate them or use the wildcard, '*'. For more information, [click here](https://docs.benchling.com/docs/getting-started-1#returning-query-parameter). - `rowDataFormat` (enum, optional) — The format of the row data, either `csv` or `parquet`. Default is `csv`. - Allowed values: `csv`, `parquet` ## Response ### 200 OK - `errorMessage` (string, optional, nullable) - `uploadStatus` (enum, optional) - Allowed values: `IN_PROGRESS`, `SUCCEEDED`, `FAILED_VALIDATION`, `NOT_UPLOADED` - `manifest` (list of DataFrameManifestItems, optional) - `columns` (list of DataFrameColumnMetadata, optional) - `id` (string, optional) - `name` (string, optional) — The user-facing name for this DataFrame. ## Errors ### 403 Forbidden Error Forbidden - `error` (ForbiddenErrorError, optional) ### 404 Not Found Error Not Found - `error` (NotFoundErrorError, optional) ## Types ### DataFrameManifestItems List of files composing a data frane, their names, and their corresponding URLs. - `fileName` (string, optional) - `url` (string, optional, nullable) ### DataFrameColumnMetadata - `displayName` (string, optional) - `type` (DataFrameColumnTypeMetadata, optional) ### ForbiddenErrorError - `invalidId` (string, optional) - `message` (string, optional) - `type` (string, optional) - `userMessage` (string, optional) ### NotFoundErrorError - `message` (string, optional) - `type` (enum, optional) - Allowed values: `invalid_request_error` - `userMessage` (string, optional) - `invalidId` (string, optional) ### DataFrameColumnTypeMetadata - `isList` (boolean, required) - `isNullable` (boolean, required) - `name` (enum, optional) - Allowed values: `String`, `Int`, `Float`, `JSON`, `DateTime`, `Date`, `Boolean`, `ObjectLink` - `target` (DataFrameColumnTypeMetadataTarget, optional) — Only present if the column type is ObjectLink ### DataFrameColumnTypeMetadataTarget Only present if the column type is ObjectLink - `baseTypeName` (string, optional) - `schemaId` (string, optional, nullable) ## Examples ### 1 Succeeded **Response** ```json { "errorMessage": null, "uploadStatus": "SUCCEEDED", "manifest": [ { "fileName": "09-14-2022_011620_PM_well_plate-part-00000.csv", "url": "https://benchling-location.s3.amazonaws.com/deploys/location/data_frames/.../09-14-2022_011620_PM_well_plate-part-00000.csv?..." } ], "columns": [ { "displayName": "Name", "type": { "isList": false, "isNullable": false, "name": "String" }, "systemName": "name" } ], "id": "dset_LlDFupKyErxx", "name": "09-14-2022 01:16:20 PM well plate" } ``` **SDK Code** ```python 1 Succeeded import requests url = "https://{tenant_name}.benchling.com/api/v2/data-frames/dset_LlDFupKyErxx" headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers) print(response.json()) ``` ```javascript 1 Succeeded const url = 'https://{tenant_name}.benchling.com/api/v2/data-frames/dset_LlDFupKyErxx'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ### 2 Failed Validation **Response** ```json { "errorMessage": "Invalid CSV File.", "uploadStatus": "FAILED_VALIDATION", "manifest": [ { "fileName": "09-14-2022_011620_PM_well_plate-part-00000.csv", "url": null } ], "id": "dset_LlDFupKyErxx", "name": "09-14-2022 01:16:20 PM well plate" } ``` **SDK Code** ```python 2 Failed Validation import requests url = "https://{tenant_name}.benchling.com/api/v2/data-frames/dset_LlDFupKyErxx" headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers) print(response.json()) ``` ```javascript 2 Failed Validation const url = 'https://{tenant_name}.benchling.com/api/v2/data-frames/dset_LlDFupKyErxx'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ### 3 In Progress **Response** ```json { "errorMessage": null, "uploadStatus": "IN_PROGRESS", "manifest": [ { "fileName": "09-14-2022_011620_PM_well_plate-part-00000.csv", "url": null } ], "id": "dset_LlDFupKyErxx", "name": "09-14-2022 01:16:20 PM well plate" } ``` **SDK Code** ```python 3 In Progress import requests url = "https://{tenant_name}.benchling.com/api/v2/data-frames/dset_LlDFupKyErxx" headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers) print(response.json()) ``` ```javascript 3 In Progress const url = 'https://{tenant_name}.benchling.com/api/v2/data-frames/dset_LlDFupKyErxx'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ### 4 Not Uploaded **Response** ```json { "errorMessage": null, "uploadStatus": "NOT_UPLOADED", "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?..." } ], "id": "dset_LlDFupKyErxx", "name": "09-14-2022 01:16:20 PM well plate" } ``` **SDK Code** ```python 4 Not Uploaded import requests url = "https://{tenant_name}.benchling.com/api/v2/data-frames/dset_LlDFupKyErxx" headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers) print(response.json()) ``` ```javascript 4 Not Uploaded const url = 'https://{tenant_name}.benchling.com/api/v2/data-frames/dset_LlDFupKyErxx'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ```