Skip to navigation
SDK Techniques

Get a Large Number of Entities by Name

Look up thousands of custom entities by name, staying within the per-request name filter limit by chunking the name list.

This recipe uses the V3 API through the V3 Python SDK. The custom entity list endpoint is stable, so the client doesn’t need early_access. long_list_of_entity_names is a placeholder for your own list of names.

  1. SDK boilerplate

    Import the V3 SDK and instantiate the client. Pass your tenant’s root URL and your API key; the SDK adds /api/v3 itself.

  2. Write a chunking helper

    A generator that yields successive slices of a list. The name filter accepts at most 100 names per request, so a list of thousands of names has to be split up.

  3. Iterate the chunks

    Drop any None entries first, then handle one chunk of at most 100 names per pass of the loop.

  4. Request the entities

    One list call per chunk. Use name_any_of_case_sensitive rather than name_any_of: the case-insensitive filter can be non-performant. The SDK sends the names as a comma-separated name.anyOf.caseSensitive query parameter on GET /api/v3/custom-entity/items.

    Iterating the pager fetches every page of matches, so a chunk that matches more than page_size entities still returns all of them. The response tab shows the shape of one page, trimmed for brevity.

from benchling_v3_sdk import Benchling
benchling = Benchling(
    base_url="https://yourcompany.benchling.com",
    api_key="<your-api-key>",
)
def chunks(lst, n):
    for i in range(0, len(lst), n):
        yield lst[i:i + n]
names = [name for name in long_list_of_entity_names if name is not None]
entities = []
for chunk_of_names in chunks(names, 100):
    for entity in benchling.custom_entity.list(name_any_of_case_sensitive=chunk_of_names, page_size=100):
        entities.append(entity)
print(len(entities))

V3 returns the standard {items, nextToken} envelope rather than V2’s {customEntities, nextToken}, and uses typedSchema in place of the deprecated schema field.