Skip to navigation
Transfers

Single Transfer: Transfer Into Non-Empty Container

Transfer a fixed volume into a container that already has contents, then read back the combined contents.

One of three transfer variants. See Introduction to Transfers for the concepts, and Source Container or Unlimited Source for the other two.

This example uses the V3 API through the V3 Python SDK. container.get and container.transfer are stable, so the client doesn’t need early_access.

  1. Imports and config

    Import the SDK and the two input models this example needs, and read the tenant URL and API key from the environment rather than hard-coding them. Then initialize the client.

  2. Destination and source

    Both containers are fetched here, not just the source. The destination is not empty, so this prints its contents before the transfer for comparison.

  3. Transfer quantity

    A fixed 5mL rather than the source’s full volume. V3 measurements take a unit ID, so this reuses the unit of the source container’s quantity, which is mL in this example.

  4. Perform the transfer

    V3 transfers have no destination_contents, so the request only names the destination, the source container, and the quantity. V3 works out the combined contents and recalculates their concentrations itself. container.transfer starts an async task, and wait_for_task_response polls it until it finishes.

  5. Check the result

    Read the destination again to see the contents and concentrations it holds after the transfer.

import os
from benchling_v3_sdk import Benchling, MeasurementInput, SingleTransferInput
TENANT_URL = os.environ.get("TENANT_URL")
API_KEY = os.environ.get("API_KEY")
benchling = Benchling(base_url=TENANT_URL, api_key=API_KEY)
destination_well = benchling.container.get("con_W5llmhfe")
source_well = benchling.container.get("con_m4AXFaoE")
for content in destination_well.contents:
    print(content.entity.id, content.concentration)
volume = MeasurementInput(value=5, unit_id=source_well.quantity.unit.id)
link = benchling.container.transfer(
    transfers=[
        SingleTransferInput(
            destination_container_id=destination_well.id,
            source_container_id=source_well.id,
            transfer_quantity=volume,
        )
    ]
)
benchling.wait_for_task_response(link)
destination_well = benchling.container.get(destination_well.id)
for content in destination_well.contents:
    print(content.entity.id, content.concentration)

Diluting in the same transfer

To top the destination up to a target volume as part of the transfer, set final_quantity. V3 recalculates every concentration for the final volume, so a dilution into a non-empty container takes one transfer rather than a transfer and a separate update:

Python
link = benchling.container.transfer(
    transfers=[
        SingleTransferInput(
            destination_container_id=destination_well.id,
            source_container_id=source_well.id,
            transfer_quantity=volume,
            final_quantity=MeasurementInput(value=20, unit_id=source_well.quantity.unit.id),
        )
    ]
)
benchling.wait_for_task_response(link)

final_quantity has to be at least the destination’s existing quantity plus the transfer quantity. A lower value is accepted, but the task fails with “Your request is invalid”, which wait_for_task_response raises as a TaskFailureException.