Dead code — organization_id can never be a list

organization_id is declared as Optional[str] (a FastAPI Query parameter), so the isinstance(organization_id, list) branch is unreachable. The comment above it ("If a list is passed …") suggests this was written for a future or hypothetical calling convention that does not exist. This dead branch adds maintenance confusion and should be removed.

Unused datetime import

datetime is imported but not referenced anywhere in this file. TeamListItem does not declare any datetime fields, and the parent class LiteLLM_TeamTable handles its own datetime imports internally.

Org admin querying own user_id silently downgrades to regular-user scope

When an org admin calls the endpoint with user_id=<their own ID>, allowed_route_check_inside_route returns True (because user_id == user_api_key_dict.user_id). This short-circuits before the org admin lookup runs, so org_admin_org_ids stays None. The code then falls into the elif not is_proxy_admin: branch and injects the caller's user_id, giving the org admin only their direct team memberships — not all teams in their organisation.

Compare this with the legacy _authorize_and_filter_teams (line 3568) which explicitly comments:

# Check if user is an org admin (even for own queries, so they see org teams)

and always fetches allowed_org_ids regardless of is_own_query.

The fix is to move the org admin DB lookup before the passes_route_check short-circuit, then use org_admin_org_ids is None and not passes_route_check as the rejection condition. This mirrors the legacy endpoint's intent and ensures org admins always see org-scoped teams even when querying with their own user_id.

Behavioral divergence from legacy endpoint: org admin direct memberships are dropped

The legacy _authorize_and_filter_teams explicitly returns org teams + any teams the org admin is a direct member of (even teams whose organization_id is not one of theirs), as documented in its docstring:

Org admins: teams from their orgs + teams they are direct members of.

The new code unconditionally sets user_id = None and scopes results purely to org_admin_org_ids. This means if an org admin is a direct member of a team that belongs to a different org (or no org), that team will be visible on /team/list but missing from /v2/team/list.

Because this PR is framed as a UI migration from the legacy endpoint, this silent drop in scope could cause org admins to see fewer teams in the new UI without any explanation. If the narrower scope is intentional, it should be documented in the PR description and in the endpoint docstring.

Caller-supplied user_id query param is silently discarded for org admins

When an org admin passes ?user_id=X to filter teams by a specific user, the code unconditionally sets user_id = None and returns all org-scoped teams instead. There is no error, no warning log, and no documentation in the endpoint's docstring explaining that user_id is ignored for org admins. A caller who legitimately wants to filter teams by user within their org will receive unexpected, unfiltered results.

At minimum, add a note to the docstring, or consider logging a debug message when a non-None user_id is discarded:

            if user_id is not None:
                verbose_proxy_logger.debug(
                    "list_team_v2: org admin user_id filter (%s) ignored; using org scope instead",
                    user_id,
                )
            user_id = None

Silent exception swallowing demotes org admins without any trace

The bare except Exception: return None silently discards any error from get_user_object (DB timeout, connection error, unexpected schema, etc.). When that happens the function returns None, org_admin_org_ids stays None, and the org admin falls through to the allowed_route_check_inside_route branch — producing a 401 or narrowed scope with no log entry to diagnose why.

Note that the legacy _authorize_and_filter_teams (line 3544) does not wrap get_user_object in a try/except — it lets the error propagate, which is the safer behaviour.

At minimum, log the caught exception before returning None so the problem is surfaced in the proxy logs:

    except Exception as e:
        verbose_proxy_logger.warning(
            "_get_org_admin_org_ids: failed to fetch user=%s: %s",
            user_id,
            str(e),
        )
        return None

members_with_roles fully loaded just to compute a count

Every team's members_with_roles JSON blob is fetched from the database and deserialized into Python memory purely to call len() on it. For large deployments where teams have hundreds or thousands of members this needlessly inflates the query payload.

If a lightweight count is needed, consider storing members_count as a denormalized integer column on LiteLLM_TeamTable that is incremented/decremented on add/remove operations, or use a Prisma _count aggregate in the select clause, so the wire payload stays small regardless of team size.

Extra DB/cache lookup added to every non-admin request

_get_org_admin_org_ids (which calls get_user_object) is now invoked unconditionally for every non-proxy-admin call to /v2/team/list, even for plain regular users who will never be org admins. While get_user_object has a cache layer, a cache miss still issues a DB query and the added cache-hit overhead is on every request.

Consider short-circuiting the check using a cheaper signal first — e.g. checking user_api_key_dict.user_role against LitellmUserRoles.ORG_ADMIN before calling into _get_org_admin_org_ids. If the JWT/key auth already has the role set, no extra DB call is needed.

Explicit organization_id filter silently widened when team_id + user_id are also set

When an org admin calls the endpoint with ?organization_id=org1&user_id=user1&team_id=team1, the following happens:

1. Line 3271 sets where_conditions["organization_id"] = "org1" (the caller's explicit filter).
2. Line 3297–3298 then overwrites it with {"in": org_admin_org_ids}, which may include org1, org2, org3, etc.

The result is that the query searches all of the admin's organizations instead of just org1, directly contradicting the caller's filter. The access-control check (line 3416) guarantees org1 is valid, but it does not prevent the scope from being silently expanded.

The fix is to honour the already-set organization_id value when team_id is also present:

            if team_id is not None:
                # team_id is already in where_conditions; keep the
                # user-supplied organization_id if present, otherwise
                # scope to all admin orgs.
                if "organization_id" not in where_conditions:
                    where_conditions["organization_id"] = {"in": org_admin_org_ids}

Direct DB query violates helper-function rule

prisma_client.db.litellm_usertable.find_unique is a raw Prisma call in the request path. The repository policy requires all DB access to go through the canonical helper functions (get_user_object, get_team_object, etc.) so that caching, metrics, and circuit-breaking are applied uniformly.

The get_user_object helper already exists, supports caching via user_api_key_cache, and is used correctly by _get_org_admin_org_ids just above. The same helper should be used here instead of calling Prisma directly, which would require threading user_api_key_cache and proxy_logging_obj into _build_team_list_where_conditions — both are already available in list_team_v2.

Rule Used: What: In critical path of request, there should be... (source)

No unit tests cover the new org-admin access control paths

This PR introduces two new code paths that are exercised only through the org-admin branch:

• org admin with a valid organization_id filter → 200
• org admin with an invalid organization_id filter → 403
• org admin without any filter → org-scoped teams

The test diff shows only updates to test_list_team_v2_security_check_non_admin_user_own_teams to accommodate the new get_user_object mocking; no new test functions covering these paths appear in the diff. The PR description says these scenarios were "manually verified via unit tests," but since these tests aren't in the repo they won't protect against regressions.

At minimum, the following cases should have dedicated tests:

1. An org admin whose organization_id filter is within their orgs gets 200 with org-scoped results.
2. An org admin whose organization_id filter is from a different org gets 403.
3. A user with no org memberships is rejected with 401 (verifying the org-admin path doesn't accidentally grant access).

Org scope is silently dropped when org admin provides user_id + no organization_id

When an org admin calls the endpoint with ?user_id=<anyone> but no organization_id, the condition:

elif org_admin_org_ids is not None and not user_id:
    where_conditions["organization_id"] = {"in": org_admin_org_ids}

evaluates to False (because user_id is truthy), so no organisation filter is injected. The resulting query then returns all teams of the specified user — from any organisation on the platform — without validating that those teams belong to the org admin's organisations.

The legacy _authorize_and_filter_teams is also permissive here (it returns org-teams ∪ user's-member-teams), so this isn't a regression relative to the legacy endpoint. However, the endpoint docstring and the PR's stated invariant ("Org admins can query teams within their organizations") both imply a narrower scope than what is actually enforced.

If the intention is to allow an org admin to look up teams for an arbitrary user, this should be explicitly documented in the docstring. If the intention is strict org-scoping, consider applying both filters simultaneously:

elif org_admin_org_ids is not None:
    conditions = {"organization_id": {"in": org_admin_org_ids}}
    if not user_id:
        where_conditions.update(conditions)
    # user_id path will further intersect via team_id IN user_team_ids

Fragile call-order dependency in mock

The call_count counter ties the test's correctness to the exact invocation order of get_user_object across two separate internal functions (_get_org_admin_org_ids and _build_team_list_where_conditions). If either function is refactored to reorder, add, or cache the call, the mock silently returns the wrong user without any assertion failure, making bugs very hard to diagnose.

A more robust pattern is to use side_effect keyed on the user_id kwarg so the mock is order-independent:

async def mock_get_user_object(**kwargs):
    uid = kwargs.get("user_id")
    if uid == "org_admin_user":
        return mock_org_admin
    if uid == "target_user":
        return mock_target_user
    return None

Narrowed exception scope changes observable error behavior

The old code caught except Exception and converted all get_user_object failures into a 404 User not found. The new code only catches ValueError. This means any non-ValueError exception from get_user_object (DB connection timeout, prisma_client being None inside the helper, unexpected schema error, etc.) will now propagate up as an unhandled 500 instead of a 404.

While semantically more correct (a DB timeout is not a "user not found"), this is a observable behavior change for API callers who previously received a 404 and may now receive a 500. If the only exception get_user_object ever raises for a missing user is indeed ValueError, then a comment to that effect would clarify the intent. If other exceptions are possible for the "user does not exist" case, they should also be caught:

        except (ValueError, SomeOtherExpectedError):
            raise HTTPException(
                status_code=404,
                detail={"error": f"User not found, passed user_id={user_id}"},
            )