Skip to main content
v2026.11,986 entries · CC-BY 4.0

Benchling API: V2, V3, Python SDK, Auth and Rate Limits

How to use the Benchling API: choose V2 or V3, install the Python SDK, authenticate, list records and handle 429 rate limits.

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")
  1. Install benchling-sdk in a virtual environment.
  2. Build the Benchling client with your tenant URL and one of the two auth methods above.
  3. Call benchling.dna_sequences.list(); it returns an iterable of pages, not a flat list.
  4. 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-remaining before 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 the url argument.
  • Beta endpoint rejected: V3 beta endpoints need the EARLY-ACCESS: true header, or early_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

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.

Benchling API rate limits and V2/V3 listing parameters
Limit or parameterValueUnitScope
Request rate: user API keys60requests per 30 secondsTenant-wide, all user keys
Request rate: app key300requests per 30 secondsPer app key
Request rate: all apps1000requests per 30 secondsTenant-wide, all apps (not reported in headers)
V3 listing page size, default50items per pageV3 list endpoints
V3 listing page size, maximum100items per pageV3 list endpoints
Max recommended backoff cap (example)15secondsExponential backoff with jitter after HTTP 429
Breaking-change notice, V3 stable90daysV3 stable API

Sources

Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.

Follow CASRAI

Research-administration guidance, standards updates and independent tool reviews.

Ask CASRAI · free to try

Ask about Benchling API: V2, V3, Python SDK, Auth and Rate Limits

2 free questions a day, no account.

An AI assistant for research: funder rules, compliance, methods and publishing. It links the sources behind its answers and labels answers that come from a web search.

Answers draw on CASRAI's guides and dictionary plus the federal and funder documents we index: Federal Register, Grants.gov, Regulations.gov and UKRI.

Works on this site and inside Claude, Cursor and the AI tools you already use.

Everything CASRAI publishes — this page, the dictionary, the guides and the news — stays open to read, with no account and no card.

Referenced across the research world

University of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logoUniversity of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logo
  • University of Cambridge logo
  • Columbia University logo
  • Crossref logo
  • University of Edinburgh logo
  • Harvard University logo
  • University of Oxford logo
  • Princeton University logo
  • Stanford School of Medicine logo
  • University College London logo
  • ORCID logo

View CASRAI adoption →