Benchling SDK for Python

1.24.1 · active · verified Thu Apr 16

The Benchling SDK for Python provides a robust interface for interacting with the Benchling Platform, enabling programmatic access to its various functionalities including entities, assays, results, and workflows. It simplifies API interactions, handles authentication, and supports common data structures. The current version is 1.24.1, with frequent releases to keep pace with platform updates.

Common errors

```
ModuleNotFoundError: No module named 'benchling_sdk'
```
cause The `benchling-sdk` package is not installed or the Python environment is incorrect.

fix Ensure the package is installed in your active environment: `pip install benchling-sdk`
```
benchling_sdk.lib.api_client_error.BenchlingApiClientError: 401 Unauthorized
```
cause Invalid or missing `BENCHLING_API_KEY` or `BENCHLING_API_URL` environment variables.

fix Set `BENCHLING_API_KEY` and `BENCHLING_API_URL` environment variables correctly. Double-check your API key and URL for typos or expiration.
```
benchling_sdk.lib.api_client_error.BenchlingApiClientError: 400 Bad Request (Validation Error)
```
cause The data sent in the request body (e.g., when creating an entity) does not conform to the expected API schema, or an enum value was passed as a string instead of an enum member.

fix Review the specific error details in the API response message. Ensure all required fields are present and their types/formats match the API documentation for the endpoint. If using enums (for v1.23.0+), pass the actual enum member (e.g., `PartType.DNA_OLIGO`) rather than a string.

Warnings

breaking As of `benchling-sdk` v1.23.0, API class methods and client initialization no longer accept string arguments for enum types. You must pass actual enum members.
Fix: Replace string literals (e.g., `'DNA_OLIGO'`) with actual enum members (e.g., `PartType.DNA_OLIGO`). Refer to the specific enum class for valid members.
gotcha The SDK's pagination mechanism has evolved. Direct access to `response.results` might be deprecated or behave differently in newer versions compared to `response.items` or explicit iterators.
Fix: Prefer `response.items` for the current page's results or use `response.to_iterator()` for efficient iteration over all pages. Always check the official documentation for the recommended pagination pattern.
gotcha Benchling API has rate limits. Frequent or large requests without proper handling can lead to `429 Too Many Requests` errors.
Fix: Implement retry logic with exponential backoff. Monitor `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers in the response for current rate limit status.

Install

pip install benchling-sdk Install latest version

Imports

BenchlingClient

from benchling_sdk.benchling import BenchlingClient

Quickstart

Initializes the BenchlingClient using environment variables for authentication and fetches a list of entries as a basic connectivity test. Ensure `BENCHLING_API_KEY` and `BENCHLING_API_URL` are set.

import os
from benchling_sdk.benchling import BenchlingClient

# Ensure BENCHLING_API_KEY and BENCHLING_API_URL are set as environment variables
api_key = os.environ.get("BENCHLING_API_KEY", "")
api_url = os.environ.get("BENCHLING_API_URL", "")

if not api_key or not api_url:
    print("Please set BENCHLING_API_KEY and BENCHLING_API_URL environment variables.")
    # In a real application, you might raise an exception or configure differently.
    exit(1)

try:
    # Initialize the client. It automatically picks up BENCHLING_API_KEY and BENCHLING_API_URL.
    benchling_client = BenchlingClient()

    # Example: List up to 3 entries (requires appropriate permissions)
    entries = benchling_client.entries.list(page_size=3).items

    print(f"Successfully connected to Benchling. Found {len(entries)} entries.")
    for entry in entries:
        print(f"  - Entry ID: {entry.id}, Name: {entry.name}")

except Exception as e:
    print(f"An error occurred: {e}")

view raw JSON →