## List

`zones.groups.list(strzone_id, GroupListParams**kwargs)  -> GroupListResponse`

**get** `/zones/{zoneId}/groups`

Returns a paginated list of the groups in the specified zone. Use cursor pagination via `after`/`before`. Sort: comma-separated field list; prefix with `-` for descending (allowed: created_at, name, identifier). Pass `expand[]=member_count` to include each group's member count, `expand[]=roles` to include the identifiers of the roles assigned to each group, and `expand[]=total_count` to include the matching row count. Filter by exact identifier via `filter[identifier]` (repeatable, OR'd across values). Search via `query[]` (case-insensitive substring match, OR'd across repeated values); it matches the group's name and identifier. Pass `filter[id]` (repeatable, max 100) to restrict results to a known set of groups — mutually exclusive with `after`/`before` (returns 400 if combined). When `filter[id]` is set, `limit` is ignored and the response contains every requested group that exists in the zone, in a single page. IDs not in the zone are silently omitted.

### Parameters

- `zone_id: str`

- `after: Optional[str]`

  Cursor for forward pagination

- `before: Optional[str]`

  Cursor for backward pagination

- `expand: Optional[Union[Literal["total_count", "member_count", "roles"], List[Literal["total_count", "member_count", "roles"]]]]`

  - `Literal["total_count", "member_count", "roles"]`

    - `"total_count"`

    - `"member_count"`

    - `"roles"`

  - `List[Literal["total_count", "member_count", "roles"]]`

    - `"total_count"`

    - `"member_count"`

    - `"roles"`

- `filter_id: Optional[Union[str, SequenceNotStr[str]]]`

  Restrict results to groups with this ID. Repeatable, max 100. Mutually exclusive with after/before.

  - `str`

    Restrict results to groups with this ID. Repeatable, max 100. Mutually exclusive with after/before.

  - `SequenceNotStr[str]`

- `filter_identifier: Optional[Union[str, SequenceNotStr[str]]]`

  Filter by exact group identifier

  - `str`

    Filter by exact group identifier

  - `SequenceNotStr[str]`

- `limit: Optional[int]`

  Maximum number of items to return

- `query: Optional[Union[str, SequenceNotStr[str]]]`

  Search across name and identifier (substring match)

  - `str`

    Search across name and identifier (substring match)

  - `SequenceNotStr[str]`

- `sort: Optional[str]`

  Comma-separated sort fields. Prefix with - for descending. Allowed: created_at, name, identifier

### Returns

- `class GroupListResponse: …`

  - `items: List[Group]`

    - `id: str`

      Unique identifier of the group

    - `created_at: datetime`

      Entity creation timestamp

    - `external: bool`

      Whether the group is synced from an external directory. When true the group is directory-owned and its membership is read-only; when false it is managed in Keycard. Read-only: set by external sync, never by the caller.

    - `identifier: str`

      User-specified identifier, unique within the zone. Automatically assigned for groups from an external directory.

    - `name: str`

      Human-readable group name

    - `organization_id: str`

      Organization this group belongs to

    - `updated_at: datetime`

      Entity update timestamp

    - `zone_id: str`

      Zone this group belongs to

    - `member_count: Optional[int]`

      Number of users in the group. Included only when requested via `expand[]=member_count` (group get or list).

    - `roles: Optional[List[str]]`

      Identifiers of the roles assigned to the group; members inherit them. Deduped across scopes. Included only when requested via `expand[]=roles` (group get or list).

  - `pagination: Pagination`

    Cursor-based pagination metadata

    - `after_cursor: Optional[str]`

      An opaque cursor used for paginating through a list of results

    - `before_cursor: Optional[str]`

      An opaque cursor used for paginating through a list of results

    - `total_count: Optional[int]`

      Total number of items matching the query. Only included when expand[]=total_count is requested.

### Example

```python
import os
from keycardai_api import KeycardAPI

client = KeycardAPI(
    api_key=os.environ.get("KEYCARD_API_API_KEY"),  # This is the default and can be omitted
)
groups = client.zones.groups.list(
    zone_id="zoneId",
)
print(groups.items)
```