Written and maintained by CASRAI Editorial Board
Published
On this page
The Benchling API is the programmatic interface to a Benchling tenant: you send authenticated HTTPS requests to https://{tenant_name}.benchling.com/api/v3 (or the older V2 equivalent) to list, create and update records such as DNA sequences, and Benchling publishes official Python SDKs that wrap those calls, handle pagination and retry after rate-limit errors. For new integrations Benchling’s documentation recommends V3; V2 has not been retired and does not need to be migrated away from.
What the Benchling API is used for in research
Lab teams reach for the API when a task has to run without someone clicking through the interface: pulling registered sequences into an analysis notebook, pushing instrument or pipeline results into a Benchling record, syncing entities with another system, or exporting data in bulk. Benchling’s V3 overview lists broader coverage than V2, including notebook documents, procedures and bulk import and export, so integrations that touch notebook content are the main reason to start on V3.
The API sits underneath the notebook and registry features described in our Benchling ELN guide, which covers entry-creation limits and a worked V3 example. This page is the developer-side companion: which API version and SDK to pick, how to authenticate, how to make a first call, and how to stay inside the rate limits. For how these data platforms differ from sample-tracking systems, see LIMS vs LIS.
Benchling API: V2, V3 and the Python SDK
Benchling currently documents two API generations and two Python packages. Both SDKs accept the same token, and the documentation states that they can be used together, so a codebase can move one workflow at a time.
| Item | V2 | V3 |
|---|---|---|
| Status in the docs | Not retired; no need to migrate | Recommended for new development |
| Base path | The V2 API reference | https://{tenant_name}.benchling.com/api/v3 |
| Python SDK package | benchling-sdk |
benchling-v3-sdk-python |
| List responses | Results under results |
Results under items, pageSize default 50, maximum 100, with nextToken |
| Stability | Stability Guidelines apply | Stable (default, 90-day notice before breaking changes) and beta (requires the EARLY-ACCESS: true header) |
What V3 adds
V3 adds :batch-create and :batch-update actions that take inline JSON, and asynchronous :bulk-* actions that work from files. It also lets you choose which fields come back with returning and omit, and supports filters such as createdAt.gt. In the V3 Python SDK, beta endpoints are enabled by passing early_access="true".
Which one should a new project use?
Start on V3 unless the endpoint you need is only documented under V2. Because the two SDK packages can run side by side and share a token, you do not have to choose once for the whole project. The rest of this page uses the V2 SDK (benchling-sdk) for the code samples because that is the package whose getting-started page shows complete install, authentication and listing examples.
Install the SDK
The V2 SDK is described in Benchling’s documentation as a Python 3.7+ SDK. Install the stable release from PyPI with pip or Poetry:
pip install benchling-sdk
poetry add benchling-sdk
Preview releases are available with pip install benchling-sdk --pre or poetry add benchling-sdk --allow-prereleases. Benchling labels preview builds as alpha functionality that is not intended for production use, so keep them out of anything that runs unattended.
Authenticate to a Benchling tenant
There are two supported ways to authenticate with the SDK, and both take your tenant URL as the url argument.
Option 1: API key
An API key is the shortest route for a personal script. Pass it through ApiKeyAuth:
from benchling_sdk.benchling import Benchling
from benchling_sdk.auth.api_key_auth import ApiKeyAuth
benchling = Benchling(
url="https://my.benchling.com",
auth_method=ApiKeyAuth("api_key"),
)
Option 2: OAuth client credentials from a Benchling app
For a service or shared integration, create a Benchling app and take the client ID and client secret from the app’s settings page. Pass them through ClientCredentialsOAuth2:
from benchling_sdk.benchling import Benchling
from benchling_sdk.auth.client_credentials_oauth2 import ClientCredentialsOAuth2
auth_method = ClientCredentialsOAuth2(
client_id="{id_here}",
client_secret="{secret_here}",
)
benchling = Benchling(
url="https://{tenant_name}.benchling.com",
auth_method=auth_method,
)
Underneath, the V3 documentation describes the same authentication as V2: a POST /oauth/token request at the tenant root, with the client_credentials, authorization_code and refresh_token grants, and the returned bearer token sent on API calls. The SDK performs the token exchange for you when you use ClientCredentialsOAuth2. Keep keys and secrets in environment variables or a secrets manager rather than in source files.
Make your first call: list DNA sequences
With a client constructed, each resource is an attribute of it. The SDK’s own example lists DNA sequences:
for page in benchling.dna_sequences.list():
for sequence in page:
print(f"name: {sequence.name}nid: {sequence.id}n")
- Install
benchling-sdkin a virtual environment. - Build the
Benchlingclient with your tenant URL and one of the two auth methods above. - Call
benchling.dna_sequences.list(); it returns an iterable of pages, not a flat list. - Loop over the pages in the outer loop and over the records in each page in the inner loop.
Note the shape: list() returns an iterable of pages, so the outer loop yields pages and the inner loop yields the sequences in that page. Benchling’s documentation says the SDK takes care of connections, authentication, error handling, pagination and retries, so you normally do not write paging code yourself when you use it.
Reading the output
Each item is a typed SDK object, so fields such as name and id are attributes you read directly. The id is the value you pass to other calls that refer to the same record. If you call the REST API directly instead of through an SDK, remember the V2/V3 difference in the table above: V2 puts results under results, V3 under items, and V3 pages with pageSize and nextToken.
Rate limits and 429 handling
Benchling enforces limits on request rate and on throughput. The data table below this article lists the request-rate limits per 30-second window. Because the user-key limit is shared tenant-wide, many scripts using personal keys count against the same 60 requests per 30 seconds, whereas each app key has its own 300.
What happens when you exceed a limit
The API returns HTTP 429 “Too Many Requests” with the body “Rate limit exceeded”. The request is not queued, so your code must send it again. Benchling’s recommended approach is exponential backoff with jitter, capping the wait at something like 15 seconds. For 5XX responses it recommends backing off significantly or stopping. Three response headers report where you stand: x-rate-limit-limit, x-rate-limit-remaining and x-rate-limit-reset (seconds left in the window). The V3 documentation adds that a 429 sometimes carries a Retry-After header.
Throughput limits are separate
Throughput limits cap how many objects can be created or updated over hours rather than seconds. They are dynamic, and Benchling describes the order of magnitude as tens of thousands of objects an hour. Throughput limits are not reported in the headers. Support can raise limits on request.
Troubleshooting
- 429 responses: slow down, retry with exponential backoff and jitter, and check
x-rate-limit-remainingbefore bursts. Consider batch actions in V3 (:batch-create,:batch-update) to send fewer requests for the same work. - Handling page objects instead of records:
list()returns an iterable of pages; use the nested loop shown above to reach the records. - Tenant URL: the documented form is
https://{tenant_name}.benchling.com; the client needs it as theurlargument. - Beta endpoint rejected: V3 beta endpoints need the
EARLY-ACCESS: trueheader, orearly_access="true"in the V3 SDK. - Using a pre-release in production: preview SDK builds are alpha; return to the stable release.
- Non-Python languages: Benchling publishes an OpenAPI specification for V2 that can be used with a generator such as OpenAPI Generator, but states that it does not test those generators.
Plan and pricing questions are separate from API behaviour; our Benchling pricing comparison explains how that is handled. If you are weighing public scholarly APIs for related metadata work, the Crossref REST API is a public scholarly-metadata API that sits at the other end of the spectrum from a tenant-scoped lab platform API.
Frequently asked questions
Is the Benchling API V2 or V3?
Both exist. Benchling’s documentation recommends V3 for new development and states that V2 is not retired and does not need to be migrated.
What is the Python package for the Benchling API?
benchling-sdk for V2 and benchling-v3-sdk-python for V3. Both accept the same token and can be used together.
How do I authenticate to the Benchling API?
Either with an API key (ApiKeyAuth) or with OAuth client credentials from a Benchling app (ClientCredentialsOAuth2), each combined with your tenant URL.
What is the Benchling API rate limit?
Per 30 seconds: 60 requests tenant-wide for all user keys, 300 per app key, and 1,000 tenant-wide for all apps. Separate, dynamic throughput limits apply over hours.
What does a 429 error from Benchling mean?
You exceeded a rate limit. The request is not queued; resend it using exponential backoff with jitter.
Sources
- Benchling developer documentation, Getting Started with the SDK, read 2026-11-15.
- Benchling developer documentation, V3 API Overview, read 2026-11-15.
- Benchling developer documentation, Rate Limiting, read 2026-11-15.
Data: Benchling API rate limits and V2/V3 listing parameters
Request-rate limits per 30-second window and pagination parameters for the Benchling API, compiled from Benchling's official rate-limiting and V3 overview documentation pages.
| Limit or parameter | Value | Unit | Scope |
|---|---|---|---|
| Request rate: user API keys | 60 | requests per 30 seconds | Tenant-wide, all user keys |
| Request rate: app key | 300 | requests per 30 seconds | Per app key |
| Request rate: all apps | 1000 | requests per 30 seconds | Tenant-wide, all apps (not reported in headers) |
| V3 listing page size, default | 50 | items per page | V3 list endpoints |
| V3 listing page size, maximum | 100 | items per page | V3 list endpoints |
| Max recommended backoff cap (example) | 15 | seconds | Exponential backoff with jitter after HTTP 429 |
| Breaking-change notice, V3 stable | 90 | days | V3 stable API |
Sources
- Benchling Rate Limiting (accessed 2026-11-15)
- Benchling V3 API Overview (accessed 2026-11-15)
Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.







