users.list(include_totals=False) raises ParsingError on a successful 200 response

[StephenWithPH]

Checklist

• I have looked into the Readme and have not found a suitable solution or answer.
• I have looked into the API documentation and have not found a suitable solution or answer.
• I have searched the issues and have not found a suitable solution or answer.
• I have searched the Auth0 Community forums and have not found a suitable solution or answer.
• I agree to the terms within the Auth0 Code of Conduct.

Description

ManagementClient.users.list(..., include_totals=False, ...) raises auth0.management.core.parse_error.ParsingError (wrapping a Pydantic ValidationError) on a successful HTTP 200 response from the Management API.

The SDK unconditionally validates the response body against ListUsersOffsetPaginatedResponseContent, which is a dict-shaped Pydantic model. But the Management API — per its public documentation and per the SDK's own docstring — returns a bare JSON array when include_totals=false. The two shapes are incompatible, and there is no branch in the SDK to handle the array case.

Observed

ParsingError: headers: {...}, status_code: 200, body: [{'user_id': 'auth0|...'}], cause: 1 validation error for ListUsersOffsetPaginatedResponseContent
  Input should be a valid dictionary or instance of ListUsersOffsetPaginatedResponseContent [type=model_type, input_value=[{'user_id': 'auth0|...'}], input_type=list]
    For further information visit https://errors.pydantic.dev/2.12/v/model_type

Note the status_code: 200 and the body: [...] (a JSON array). The API responded successfully and in the documented shape; the SDK then failed to parse the response.

Expected

The SyncPager yields UserResponseSchema items, equivalent to the behavior when include_totals=True.

Reproduction

from auth0.management import ManagementClient

client = ManagementClient(domain=..., token=...)

list(client.users.list(
    q='username:"someuser"',
    include_totals=False,
    fields="user_id",
))

Additional context

Root cause

In src/auth0/management/users/raw_client.py, RawUsersClient.list has a single success branch:

auth0-python/src/auth0/management/users/raw_client.py

Lines 135 to 143 in d381cbf

	if 200 <= _response.status_code < 300:
	_parsed_response = typing.cast(
	ListUsersOffsetPaginatedResponseContent,
	parse_obj_as(
	type_=ListUsersOffsetPaginatedResponseContent, # type: ignore
	object_=_response.json(),
	),
	)
	_items = _parsed_response.users

There is no if include_totals: branch, and the Pydantic model itself is dict-only:

auth0-python/src/auth0/management/types/list_users_offset_paginated_response_content.py

Lines 10 to 15 in d381cbf

	class ListUsersOffsetPaginatedResponseContent(UniversalBaseModel):
	start: typing.Optional[float] = None
	limit: typing.Optional[float] = None
	length: typing.Optional[float] = None
	total: typing.Optional[float] = None
	users: typing.Optional[typing.List[UserResponseSchema]] = None

There is no RootModel/list-validation fallback, so parse_obj_as cannot accept the array shape that the API returns.

Contradiction between the SDK's parameter default and the API's contract

The SDK signature:

include_totals: typing.Optional[bool] = True,

…but the SDK's own docstring (copied from the API spec) reads:

Return results inside an object that contains the total result count (true) or as a direct array of results (false, default).

And the public Management API documentation at https://auth0.com/docs/api/management/v2/users/get-users agrees: include_totals=false returns "a direct array of results."

So the API's default behavior (false) is exactly the case the SDK parser cannot handle. This very likely masked the bug in CI — the SDK's own default value (True) takes the only branch the parser supports.

Evidence that the error originates inside the SDK, not from the API

The Auth0 API returned HTTP 200 with the documented response shape. The ParsingError.__str__ formatter in src/auth0/management/core/parse_error.py produces exactly the wire format we see:

def __str__(self) -> str:
    cause_str = f", cause: {self.cause}" if self.cause is not None else ""
    return f"headers: {self.headers}, status_code: {self.status_code}, body: {self.body}{cause_str}"

The cause is a Pydantic ValidationError against ListUsersOffsetPaginatedResponseContent — i.e., the SDK choking on a valid response.

auth0-python version

5.4.0

Python version

3.10