Memberships API
TeamMembershipCollection reference — get, get_or_none, list, iter, count, one, and first for memberships on a team, plus the TeamMembership and User objects.
TeamMembershipCollection is accessed via Team.memberships. Each Team object returned by the Teams API carries a bound collection for that team's memberships.
team = proj.teams.get("team_abc123")
memberships = team.memberships # TeamMembershipCollectionThe TeamMembership object
TeamMembership is a frozen dataclass:
Prop
Type
The User object
User is a frozen dataclass, available when include=(\"user\",):
Prop
Type
TeamMembershipCollection.get(*, user_id, include=())
Fetch the membership record for a specific user in this team. Raises if the membership does not exist.
Keyword-only lookup
Unlike other collection get() methods, this one takes user_id as a keyword argument — not a positional one.
Signature
def get(
self,
*,
user_id: str,
include: Sequence[MembershipInclude] = (),
) -> TeamMembership: ...Parameters
Prop
Type
Returns — TeamMembership.
Side effects — Makes one HTTP read request.
Raises — NotFoundError when the user is not a member of this team. AuthenticationError when the API key is invalid or missing.
Example
membership = team.memberships.get(user_id="user_xyz", include=("user",))
print(membership.role, membership.user.email)TeamMembershipCollection.get_or_none(*, user_id, include=())
Fetch the membership for a user. Returns None instead of raising when the membership does not exist.
Signature
def get_or_none(
self,
*,
user_id: str,
include: Sequence[MembershipInclude] = (),
) -> TeamMembership | None: ...Parameters
Prop
Type
Returns — TeamMembership if found, None if not found.
Side effects — Makes one HTTP read request.
Raises — AuthenticationError when the API key is invalid or missing.
Example
m = team.memberships.get_or_none(user_id="user_xyz")
if m:
print(m.role)TeamMembershipCollection.list(...)
Return one page of memberships matching the given filters.
Signature
def list(
self,
*,
user_id: str | None = None,
role: str | None = None,
include: Sequence[MembershipInclude] = (),
limit: int = 100,
cursor: str | None = None,
order_by: MembershipOrderBy = "joined_at",
order: Literal["asc", "desc"] = "asc",
) -> Page[TeamMembership]: ...Parameters
Prop
Type
Returns — Page[TeamMembership].
Side effects — Makes one HTTP read request.
Raises — AuthenticationError when the API key is invalid or missing.
Example
page = team.memberships.list(role="admin", include=("user",))
for m in page.items:
print(m.user.email, m.joined_at)TeamMembershipCollection.iter(...)
Iterate over all memberships matching the given filters across all pages.
Signature
def iter(
self,
*,
user_id: str | None = None,
role: str | None = None,
include: Sequence[MembershipInclude] = (),
order_by: MembershipOrderBy = "joined_at",
order: Literal["asc", "desc"] = "asc",
) -> Iterator[TeamMembership]: ...Parameters
Prop
Type
Returns — Iterator[TeamMembership]: lazy, fetches pages on demand.
Side effects — Makes one HTTP read request per page.
Raises — AuthenticationError on any page fetch.
Example
for m in team.memberships.iter(include=("user",)):
print(m.user_ref.id, m.role)TeamMembershipCollection.count(*, user_id=None, role=None)
Return the count of memberships matching the given filters.
Signature
def count(
self,
*,
user_id: str | None = None,
role: str | None = None,
) -> int: ...Parameters
Prop
Type
Returns — int.
Side effects — Makes one HTTP read request.
Raises — AuthenticationError when the API key is invalid or missing.
Example
admin_count = team.memberships.count(role="admin")TeamMembershipCollection.one(...)
Return exactly one membership matching the given filters.
Signature
def one(
self,
*,
user_id: str | None = None,
role: str | None = None,
include: Sequence[MembershipInclude] = (),
) -> TeamMembership: ...Parameters
Prop
Type
Returns — TeamMembership.
Side effects — Makes one HTTP read request (fetches up to 2 items).
Raises — NotFoundError when no memberships match. MultipleResultsError when more than one match. AuthenticationError when the API key is invalid or missing.
Example
membership = team.memberships.one(user_id="user_xyz")TeamMembershipCollection.first(...)
Return the first membership matching the given filters, or None.
Signature
def first(
self,
*,
user_id: str | None = None,
role: str | None = None,
include: Sequence[MembershipInclude] = (),
) -> TeamMembership | None: ...Parameters
Prop
Type
Returns — TeamMembership if found, None otherwise.
Side effects — Makes one HTTP read request (fetches 1 item).
Raises — AuthenticationError when the API key is invalid or missing.
Example
first_admin = team.memberships.first(role="admin", include=("user",))Teams API
TeamCollection reference — get, get_or_none, list, iter, count, one, and first for teams in a project, plus the Team object and its memberships attribute.
Members API
ManagementProject.get_all_members — paginated list of all members across all teams in a project, with optional team membership sideloading.