---
title: "Create a data frame."
method: POST
path: "/data-frames"
tags: ["dataFrames"]
---

# Create a data frame.

`POST /data-frames`

## Request

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

Create a data frame.

Data frames can be created from `.csv` files, and only 1 `.csv` file can currently be uploaded.

A successful data frame upload requires 3 calls in serial:
1. [Create a data frame](https://docs.benchling.com/docs/api/v2-beta/benchling-api-beta/data-frames/create-data-frame), this endpoint, specifying the files to upload. This
   returns a `manifest` containing S3 `PUT` URLs corresponding to the files that will be uploaded for
   the 2nd call and a data frame ID for the 3rd call.
2. Upload the data frame `.csv` content to S3. Add `x-amz-server-side-encryption: AES256` to the request
   headers, because we use server-side encryption. Here is a `curl` example:
   ```bash
   curl -H "x-amz-server-side-encryption: AES256" -X PUT -T <LOCAL_FILE> -L <S3_PUT_URL>
   ```
3. [Update the data frame](https://docs.benchling.com/docs/api/v2-beta/benchling-api-beta/data-frames/patch-data-frame) to mark as `IN_PROGRESS` to start a [long-running task](https://docs.benchling.com/docs/api/v2/benchling-api/tasks/get-task)
  to process and validate the data frame.
    - For more details on how we process and validate data frames, [click here](https://docs.benchling.com/docs/datasets-ingestion-reference).

Note: Manifest URLs are valid for 1 hour after being returned from this endpoint. They should not be stored
persistently for later use.

CSV files up to 150MB are supported.

## Request body

- DataFrameCreate
  - `manifest` DataFrameCreateManifestItems[], required
    - `fileName` string
  - `name` string, required

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

- `400`: Bad Request
- `403`: Forbidden
- `404`: Not Found

---

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