---
title: "Get a data frame"
method: GET
path: "/data-frames/{data_frame_id}"
tags: ["dataFrames"]
---

# Get a data frame

`GET /data-frames/{data_frame_id}`

## Request

- Base URL: `https://{tenant_name}.benchling.com/api/v2`
- URL: `https://{tenant_name}.benchling.com/api/v2/data-frames/{data_frame_id}`
- Auth: HTTP bearer

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](https://docs.benchling.com/docs/api/v2/benchling-api/data-frames/create-data-frame) 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.

## Path parameters

- `data_frame_id` string, required

## Query parameters

- `returning` string
- `rowDataFormat` 'csv' | 'parquet'

## Response `200`

OK

- DataFrame
  - `errorMessage` string, nullable
  - `uploadStatus` 'IN_PROGRESS' | 'SUCCEEDED' | 'FAILED_VALIDATION' | 'NOT_UPLOADED'
  - `manifest` DataFrameManifestItems[]
    - `fileName` string
    - `url` string, nullable
  - `columns` DataFrameColumnMetadata[]
    - `displayName` string
    - `type` DataFrameColumnTypeMetadata
      - `name` 'String' | 'Int' | 'Float' | 'JSON' | 'DateTime' | 'Date' | 'Boolean' | 'ObjectLink'
      - `isList` boolean, required
      - `isNullable` boolean, required
      - `target` DataFrameColumnTypeMetadataTarget: Only present if the column type is ObjectLink
        - `baseTypeName` string
        - `schemaId` string, nullable
  - `id` string
  - `name` string: The user-facing name for this DataFrame.

## Other responses

- `403`: Forbidden
- `404`: Not Found

---

[API](https://skmtc.dev/benchling/apis/benchling-api-2.md) - [All operations](https://skmtc.dev/benchling/apis/benchling-api-2/llms.txt) - [OpenAPI document](https://skmtc.dev/benchling/apis/benchling-api-2/revisions/01d2fa8523cd?raw)