Benchling Python SDK and REST API integration for registry entities, inventory, ELN entries, workflows, Benchling Apps, and Data Warehouse queries. Use when automating lab data with benchling-sdk or the v2 API.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Benchling Python SDK and REST API integration for registry entities, inventory, ELN entries, workflows, Benchling Apps, and Data Warehouse queries. Use when automating lab data with benchling-sdk or the v2 API.
license
MIT
allowed-tools
Read Write Edit Bash
compatibility
Requires a Benchling account, tenant URL, and API key or OAuth app credentials. Install benchling-sdk with uv pip install.
required_environment_variables
[{"name":"BENCHLING_TENANT_URL","prompt":"Benchling tenant base URL.","required_for":"full functionality"},{"name":"BENCHLING_API_KEY","prompt":"API key auth (alternative to OAuth).","required_for":"optional features"},{"name":"BENCHLING_CLIENT_ID","prompt":"OAuth app client id.","required_for":"optional features"},{"name":"BENCHLING_CLIENT_SECRET","prompt":"OAuth app client secret.","required_for":"optional features"},{"name":"BENCHLING_PROD_TENANT_URL","prompt":"Production tenant URL (multi-env setups).","required_for":"optional features"},{"name":"BENCHLING_PROD_API_KEY","prompt":"Production API key (multi-env setups).","required_for":"optional features"},{"name":"BENCHLING_STAGING_TENANT_URL","prompt":"Staging tenant URL (multi-env setups).","required_for":"optional features"},{"name":"BENCHLING_STAGING_API_KEY","prompt":"Staging API key (multi-env setups).","required_for":"optional features"}]
Benchling is a cloud platform for life sciences R&D. Access registry entities (DNA, RNA, proteins), inventory, electronic lab notebooks, and workflows programmatically via the Python SDK and REST API.
Creating or querying electronic lab notebook entries
Building workflow automations or Benchling Apps
Syncing data between Benchling and external systems
Querying the Benchling Data Warehouse for analytics
Setting up event-driven integrations with AWS EventBridge
Core Capabilities
1. Authentication & Setup
Python SDK installation:
uv pip install "benchling-sdk==1.25.0"
Preview builds (alpha; not for production):
uv pip install "benchling-sdk" --prerelease allow
Environment variables (scoped reads only):
Read only the named keys you need — never dump or iterate over the full environment:
import os
tenant_url = os.environ.get("BENCHLING_TENANT_URL") # e.g. https://your-tenant.benchling.com
api_key = os.environ.get("BENCHLING_API_KEY")
ifnot tenant_url ornot api_key:
raise ValueError("Set BENCHLING_TENANT_URL and BENCHLING_API_KEY")
Obtain an API key from Profile Settings in Benchling. For OAuth apps, use the Developer Console and store BENCHLING_CLIENT_ID / BENCHLING_CLIENT_SECRET separately.
Authentication methods:
API key (scripts and personal automation):
from benchling_sdk.benchling import Benchling
from benchling_sdk.auth.api_key_auth import ApiKeyAuth
benchling = Benchling(
url=tenant_url,
auth_method=ApiKeyAuth(api_key),
)
OAuth client credentials (multi-user apps and production integrations):
from benchling_sdk.benchling import Benchling
from benchling_sdk.auth.client_credentials_oauth2 import ClientCredentialsOAuth2
benchling = Benchling(
url=tenant_url,
auth_method=ClientCredentialsOAuth2(
client_id=os.environ["BENCHLING_CLIENT_ID"],
client_secret=os.environ["BENCHLING_CLIENT_SECRET"],
),
)
Key points:
All API requests require HTTPS; network calls must target your tenant URL only
Authentication permissions mirror UI permissions
Verify credentials with benchling.users.get_me() before bulk operations
For detailed authentication information including OIDC and security best practices, refer to references/authentication.md.
2. Registry & Entity Management
Registry entities include DNA sequences, RNA sequences, AA sequences, custom entities, and mixtures. The SDK provides typed classes for creating and managing these entities.
# List all DNA sequences (returns a generator)
sequences = benchling.dna_sequences.list()
for page in sequences:
for seq in page:
print(f"{seq.name} ({seq.id})")
# Check total count
total = sequences.estimated_count()
Key Operations:
Create: benchling.<entity_type>.create()
Read: benchling.<entity_type>.get_by_id(id) or .list()
Some operations are asynchronous and return tasks. The SDK default max_wait_seconds for polling is 600 seconds (since SDK 1.11.0):
from benchling_sdk.helpers.tasks import wait_for_task
result = wait_for_task(
benchling,
task_id="task_abc123",
interval_wait_seconds=2,
max_wait_seconds=300, # override for long-running serverless handlers
)
Key Workflow Operations:
Create and manage workflow tasks
Update task statuses and assignments
Execute bulk operations asynchronously
Monitor task progress
6. Events & Integration
Subscribe to Benchling changes via AWS EventBridge (customer-owned bus) or Webhooks (recommended for new Benchling Apps). EventBridge delivers hydrated v2 API objects; webhooks use thinner payloads.
Common EventBridge detail-type values:
v2.dnaSequence.created, v2.dnaSequence.updated
v2.entity.registered
v2.entry.created, v2.entry.updated
v2.workflowTask.updated.status
v2.request.created
Minimal EventBridge rule (filter request creation by schema name):
defhandler(event, context):
detail_type = event["detail-type"]
detail = event["detail"]
if detail.get("deprecated"):
# Alert — migrate before Benchling removes this event typepassif detail.get("excludedProperties"):
# Payload exceeded 256 KB; re-fetch via detail["request"]["apiURL"]passif detail_type == "v2.request.created":
request_id = (detail.get("request") or {}).get("id")
# Re-fetch authoritative state — events can be late or out of order# request = benchling.requests.get_by_id(request_id)return {"request_id": request_id}
return {"status": "ignored", "detail_type": detail_type}
Setup flow:
Tenant admin creates a subscription at https://your-tenant.benchling.com/event-subscriptions
Associate the AWS partner event source with a dedicated event bus immediately (within ~12 days)
Create rules + targets (Lambda, SQS, SNS) and grant invoke permissions
Validate with a CloudWatch Logs rule, then trigger a matching Benchling action
Recovery: EventBridge deliveries are not replayed. Use the List Events API for events up to ~2 weeks old after outages.
For payload schema, CloudFormation templates, SDK list/recovery examples, and validation steps, see references/eventbridge.md.
7. Data Warehouse & Analytics
Query historical Benchling data using SQL through the Data Warehouse.
Access Method:
The Benchling Data Warehouse provides SQL access to Benchling data for analytics and reporting. Connect using standard SQL clients with provided credentials.
Common Queries:
Aggregate experimental results
Analyze inventory trends
Generate compliance reports
Export data for external analysis
Integration with Analysis Tools:
Jupyter notebooks for interactive analysis
BI tools (Tableau, Looker, PowerBI)
Custom dashboards
Best Practices
Error Handling
The SDK automatically retries failed requests:
# Automatic retry for 429, 502, 503, 504 status codes# Up to 5 retries with exponential backoff# Customize retry behavior if neededfrom benchling_sdk.retry import RetryStrategy
benchling = Benchling(
url=tenant_url,
auth_method=ApiKeyAuth(api_key),
retry_strategy=RetryStrategy(max_retries=3),
)
Pagination Efficiency
Use generators for memory-efficient pagination:
# Generator-based iterationfor page in benchling.dna_sequences.list():
for sequence in page:
process(sequence)
# Check estimated count without loading all pages
total = benchling.dna_sequences.list().estimated_count()
Load these references as needed for specific integration requirements.
Common Use Cases
1. Bulk Entity Import:
# Import multiple sequences from FASTA filefrom Bio import SeqIO
for record in SeqIO.parse("sequences.fasta", "fasta"):
benchling.dna_sequences.create(
DnaSequenceCreate(
name=record.id,
bases=str(record.seq),
is_circular=False,
folder_id="fld_abc123"
)
)
2. Inventory Audit:
# List all containers in a specific location
containers = benchling.containers.list(
parent_storage_id="box_abc123"
)
for page in containers:
for container in page:
print(f"{container.name}: {container.barcode}")
3. Workflow Automation:
# Update all pending tasks for a workflow
tasks = benchling.workflow_tasks.list(
workflow_id="wf_abc123",
status="pending"
)
for page in tasks:
for task in page:
# Perform automated checksif auto_validate(task):
benchling.workflow_tasks.update(
task_id=task.id,
workflow_task=WorkflowTaskUpdate(
status_id="status_complete"
)
)
4. Data Export:
# Export all sequences with specific properties
sequences = benchling.dna_sequences.list()
export_data = []
for page in sequences:
for seq in page:
if seq.schema_id == "target_schema_id":
export_data.append({
"id": seq.id,
"name": seq.name,
"bases": seq.bases,
"length": len(seq.bases)
})
# Save to CSV or databaseimport csv
withopen("sequences.csv", "w") as f:
writer = csv.DictWriter(f, fieldnames=export_data[0].keys())
writer.writeheader()
writer.writerows(export_data)
