---
title: "List users by role"
method: POST
path: "/structures/v1/roles/{role_id}/members/list"
tags: ["Structures"]
---

# List users by role

`POST /structures/v1/roles/{role_id}/members/list`

## Request

- Base URL: `https://api.mitti.com`
- URL: `https://api.mitti.com/structures/v1/roles/{role_id}/members/list`
- Auth: HTTP bearer

Lists the users assigned to a role, deduplicated across structure instances, one entry per user. Each entry samples the user's assigned structures per structure type.

## Path parameters

- `role_id` string, required

## Request body

- S12StructuresMembershipV1StructureMembershipServiceListUsersByRoleBody: Request message to list users assigned to a role.
  - `page_size` integer: Optional. The maximum number of users to return. Default of 1000. You can specify a value between 1 to 1000.
  - `offset` integer: Optional. The number of results to offset by.
  - `sort_direction` 'SORT_DIRECTION_UNSPECIFIED' | 'SORT_DIRECTION_ASC' | 'SORT_DIRECTION_DESC'
  - `filter` S12StructuresMembershipV1ListUsersByRoleRequestFilter: Filter criteria for listing users by role.
    - `query` string: Used for filtering users by their name, family name or email. This supports partial matches to allow flexible searching.
    - `user_status` 'USER_ACTIVE_STATUS_UNSPECIFIED' | 'USER_ACTIVE_STATUS_ACTIVE' | 'USER_ACTIVE_STATUS_DEACTIVATED': - USER_ACTIVE_STATUS_UNSPECIFIED: Status is unknown or not specified - USER_ACTIVE_STATUS_ACTIVE: User is active - USER_ACTIVE_STATUS_DEACTIVATED: User has been deactivated
  - `max_structures_per_user` integer: Optional. Maximum structures sampled per user (1-50), applied PER structure_type_id, not globally. Omit it to sample none. total_structure_count_by_type_id is never capped.

## Response `200`

A successful response.

- S12StructuresMembershipV1ListUsersByRoleResponse: Response message containing a list of users assigned to a role.
  - `users` S12StructuresMembershipV1RoleUserEntry[]: List of users assigned to the role, one entry per distinct user.
    - `user_id` string: The unique identifier of the user.
    - `assignments` S12StructuresMembershipV1RoleUserAssignments: Details and structure assignments for a user assigned to a role.
      - `user_data` S12StructuresMembershipV1UserDetails
        - `first_name` string: The user's first name.
        - `last_name` string: The user's last name.
        - `email` string: The user's email address.
        - `status` 'USER_ACTIVE_STATUS_UNSPECIFIED' | 'USER_ACTIVE_STATUS_ACTIVE' | 'USER_ACTIVE_STATUS_DEACTIVATED': - USER_ACTIVE_STATUS_UNSPECIFIED: Status is unknown or not specified - USER_ACTIVE_STATUS_ACTIVE: User is active - USER_ACTIVE_STATUS_DEACTIVATED: User has been deactivated
        - `avatar` S12StructuresMembershipV1Avatar
          - `id` string: The unique identifier of the avatar.
          - `type` string: The type of the avatar.
          - `token` string: The token used to access the avatar resource.
        - `last_seen` string, date-time: last_seen timestamp of the user
        - `seat_type` 'SUBSCRIPTION_SEAT_TYPE_UNSPECIFIED' | 'SUBSCRIPTION_SEAT_TYPE_PREMIUM' | 'SUBSCRIPTION_SEAT_TYPE_COLLABORATOR' | 'SUBSCRIPTION_SEAT_TYPE_LITE' | 'SUBSCRIPTION_SEAT_TYPE_SERVICE_USER' | 'SUBSCRIPTION_SEAT_TYPE_SUPPORT'
      - `assigned_structure_details` S12StructuresMembershipV1RoleStructureInfo[]: Sampled structures assigned to the user for this role. The sample is capped at max_structures_per_user PER structure_type_id, so each type a user belongs to is represented. Use total_structure_count_by_type_id to know the true per-type counts when a type is sampled out.
        - `structure_id` string: The unique identifier of the structure.
        - `structure_name` string: The name of the structure.
        - `structure_type_id` string: The unique identifier of the structure type.
      - `total_structure_count` integer: Total number of structures this user holds the role on.
      - `total_structure_count_by_type_id` object: Total number of structures this user holds the role on, bucketed by structure_type_id. Counts are NOT capped by max_structures_per_user, so callers can render accurate per-type overflow ("+N more") even when the sampled `assigned_structure_details` list is truncated. A missing key means the user has zero structures of that type for this role.
  - `total_count` integer: The total count of distinct users assigned to the role.
  - `offset` integer: The offset for the requested page.

## Other responses

- `default`: An unexpected error response.

## Changes

- **2026-11-03** `eb6bb843bf18`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/safetyculture/apis/safetyculture-api/changes/structures/v1/roles/:role_id/members/list/post.md)

---

[API](https://skmtc.dev/safetyculture/apis/safetyculture-api.md) - [All operations](https://skmtc.dev/safetyculture/apis/safetyculture-api/llms.txt) - [OpenAPI document](https://skmtc.dev/safetyculture/apis/safetyculture-api/revisions/eb6bb843bf18?raw)
