Collection Contract

Every collection in the Management API (TeamCollection, TeamMembershipCollection, WorkflowNodeCollection, WorkflowNodeLabelCollection, AuditEventCollection) implements the same set of methods. This page documents the generic shape and semantics. The resource-specific pages (Teams, Memberships, Workflow Nodes, Audit Events) document the exact filter parameters and return types for each collection.

collection.list(...)

Return one page of results matching the given filters.

Signature (generic shape)

def list(
    self,
    *,
    # ...resource-specific filters...
    include: Sequence[IncludeType] = (),
    limit: int = 100,
    cursor: str | None = None,
    order_by: OrderByType = "...",
    order: Literal["asc", "desc"] = "asc",
) -> Page[T]: ...

Parameters

Returns — Page[T]: a frozen dataclass with:

Side effects — Makes one HTTP read request per call.

Raises — AuthenticationError when the API key is invalid or missing.

Example

page = proj.teams.list(category="simulation", limit=50)
for team in page.items:
    print(team.name)

# Fetch next page
if page.next_cursor:
    page2 = proj.teams.list(category="simulation", limit=50, cursor=page.next_cursor)

collection.get(id, *, include=())

Fetch a single record by its ID. Raises if the record does not exist.

Signature (generic shape)

def get(self, id: str, *, include: Sequence[IncludeType] = ()) -> T: ...

Parameters

Returns — T: the requested record.

Side effects — Makes one HTTP read request.

Raises — NotFoundError when no record with the given ID exists. AuthenticationError when the API key is invalid or missing.

Example

team = proj.teams.get("team_abc123", include=("counts",))
print(team.member_count)

collection.get_or_none(id, *, include=())

Fetch a single record by its ID. Returns None instead of raising when the record does not exist.

Signature (generic shape)

def get_or_none(self, id: str, *, include: Sequence[IncludeType] = ()) -> T | None: ...

Parameters

Returns — T if found, None if the record does not exist.

Side effects — Makes one HTTP read request.

Raises — AuthenticationError when the API key is invalid or missing. Does NOT raise NotFoundError.

Example

team = proj.teams.get_or_none("team_maybe")
if team is not None:
    print(team.name)

collection.iter(...)

Iterate over all matching records across all pages. Walks pages internally using list().

Signature (generic shape)

def iter(
    self,
    *,
    # ...resource-specific filters...
    include: Sequence[IncludeType] = (),
    order_by: OrderByType = "...",
    order: Literal["asc", "desc"] = "asc",
) -> Iterator[T]: ...

Parameters

Returns — Iterator[T]: a lazy iterator. Each page is fetched on demand as you consume items.

Side effects — Makes one HTTP read request per page fetched. The number of requests equals ceil(total / page_size).

Raises — AuthenticationError on any page fetch.

Example

for node in proj.workflow_nodes.iter(label="simulation"):
    print(node.display_name)

collection.count(...)

Return the total count of records matching the given filters.

Signature (generic shape)

def count(self, *, ...filters) -> int: ...

Parameters

Returns — int: the total number of matching records.

Side effects — Makes one HTTP read request (a lightweight count query, not a full list).

Raises — AuthenticationError when the API key is invalid or missing.

Example

n = proj.teams.count(category="simulation")
print(f"There are {n} simulation teams")

collection.one(...)

Return exactly one record matching the given filters. Raises if zero or more than one record matches.

Signature (generic shape)

def one(
    self,
    *,
    # ...resource-specific filters...
    include: Sequence[IncludeType] = (),
) -> T: ...

Parameters

Returns — T: the single matching record.

Side effects — Makes one HTTP read request (fetches up to 2 items to detect ambiguity).

Raises — NotFoundError when no records match. MultipleResultsError when more than one record matches. AuthenticationError when the API key is invalid or missing.

Example

# Raises if "Photonics Team" doesn't exist or if multiple teams share that name
team = proj.teams.one(name="Photonics Team")

collection.first(...)

Return the first record matching the given filters, or None if no records match.

Signature (generic shape)

def first(
    self,
    *,
    # ...resource-specific filters...
    include: Sequence[IncludeType] = (),
) -> T | None: ...

Parameters

Returns — T if at least one record matches, None otherwise. Uses the same sort order as list().

Side effects — Makes one HTTP read request (fetches exactly 1 item).

Raises — AuthenticationError when the API key is invalid or missing. Does NOT raise NotFoundError.

Example

team = proj.teams.first(category="simulation")
if team:
    print(team.name)

Pagination

All list() methods use cursor-based pagination. Pass Page.next_cursor as the cursor= argument in the next call to advance the page. When next_cursor is None, you have reached the last page.

cursor = None
while True:
    page = proj.workflow_nodes.list(label="fdtd-sim", limit=50, cursor=cursor)
    for node in page.items:
        process(node)
    if page.next_cursor is None:
        break
    cursor = page.next_cursor

For most use cases, prefer iter() which handles pagination automatically:

for node in proj.workflow_nodes.iter(label="fdtd-sim"):
    process(node)

Include / sideloading

The include parameter requests that the server embed related objects in the response rather than returning only reference IDs. Each collection supports a fixed set of include values:

Pass multiple values as a sequence:

nodes = proj.workflow_nodes.list(
    include=("label", "properties", "attachments"),
    limit=20,
)