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

# Exporting Data with the Bulk Export API

The Bulk Export API exports large amounts of your data in one operation. The exported files are serialized JSON matching the [V3 REST API](/docs/v3-api-overview) response shape for each model, so anything you can read from a V3 listing endpoint comes back in the same form.

> **Warning**
>
> ### Private beta
>
> This API is in private beta. Contact your account team to request access.
>
> Beta operations are reached on the unified `/api/v3` base path with the `EARLY-ACCESS: true` header. Without both the header and the feature enabled on your tenant, these endpoints return `404`. See the [V3 Stability Guidelines](/docs/stability-guidelines).

Three characteristics shape how you use it:

* **Asynchronous.** An export can take from a few minutes to several hours, so you start a task and poll for its status rather than waiting on a response.
* **Multiple models per request.** One request can export several data types, for example Containers and Boxes together, with up to 100 models in a single call.
* **One export per type at a time.** A second export of a type already being exported has to wait.

## Step 1: Start the export

`POST` to `/api/v3/bulk-export` with the `models` you want to export. Each key is a model name; its value is an object that can carry `filters`. At least one model is required.

**`Endpoint`**

```text title="Endpoint"
POST /api/v3/bulk-export
EARLY-ACCESS: true
```

**`Example Request`**

```json title="Example Request"
{
  "models": {
    "Container": {
      "filters": {
        "modifiedAt": { "gte": "2026-08-15T05:22:30Z" }
      }
    },
    "Box": {}
  }
}
```

**`Example Response`**

```json title="Example Response"
{
  "taskId": "atsk_123",
  "pollingUri": "https://{tenant_name}.benchling.com/api/v3/tasks/bulk-export/atsk_123"
}
```

A model with an empty object, like `Box` above, exports without filters.

> **Note**
>
> ### Check which filters a model supports
>
> Filters are per model. `createdAt` and `modifiedAt` comparisons are the common case, but not every model supports both. Look the model up in the [V3 API reference](https://benchling.com/api/v3/reference) and use the filters its listing endpoint accepts. An unsupported filter fails the export for that model rather than being ignored.

## Step 2: Check the export status

`GET` the `pollingUri`, or build it from the `taskId`, to track progress. The response reports an overall status plus a per-model breakdown, because models complete independently.

**`Endpoint`**

```text title="Endpoint"
GET /api/v3/tasks/bulk-export/{task_id}
EARLY-ACCESS: true
```

**`Example Response`**

```json title="Example Response"
{
  "taskId": "atsk_123",
  "status": "IN_PROGRESS",
  "statusByModel": {
    "Container": {
      "status": "SUCCESS",
      "failureReason": null,
      "totalRecordsExported": 41822
    },
    "Box": {
      "status": "IN_PROGRESS",
      "failureReason": null,
      "totalRecordsExported": null
    }
  }
}
```

Both the overall `status` and each model's `status` are `IN_PROGRESS`, `SUCCESS`, or `FAILED`. Keep polling until the overall `status` leaves `IN_PROGRESS`. When a model fails, `failureReason` explains why while the rest of the export continues.

## Step 3: Download the data

Once the export reports `SUCCESS`, downloading is a two-part process. Benchling gives you a manifest per model, and each manifest lists the URLs of the actual data files.

### a. Get the manifest URLs

**`Endpoint`**

```text title="Endpoint"
GET /api/v3/tasks/bulk-export/{task_id}/successful-results
EARLY-ACCESS: true
```

**`Example Response`**

```json title="Example Response"
{
  "taskId": "atsk_123",
  "manifestFilePreSignedUrls": {
    "Container": "https://s3.amazonaws.com/bucket/Container?signature=...",
    "Box": "https://s3.amazonaws.com/bucket/Box?signature=..."
  }
}
```

`manifestFilePreSignedUrls` maps each exported model to a presigned URL for its manifest. These URLs are short-lived, so request them again if they expire before you finish downloading.

### b. Download the data files

A manifest is a plain text file holding one download URL per line. Fetch the manifest, then fetch everything it lists:

**`Download`**

```bash title="Download"
# Save the manifest for one model
curl -L "<MANIFEST_FILE_URL>" -o manifest.txt

# Download every data file the manifest lists
xargs -n 1 curl -O -L < manifest.txt
```

The downloaded files contain serialized JSON in the same shape as the model's V3 API responses, so you can feed them to the same code that parses a V3 listing.