Exporting Data with the Bulk Export API
The Bulk Export API exports whole data types as serialized JSON through an asynchronous task. Start an export for one or more models, poll for its status, then download the data files listed in a per-model manifest.
The Bulk Export API exports large amounts of your data in one operation. The exported files are serialized JSON matching the V3 REST API response shape for each model, so anything you can read from a V3 listing endpoint comes back in the same form.
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.
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.
A model with an empty object, like Box above, exports without filters.
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 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.
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
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:
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.