Use this endpoint to read who holds a role. A user who holds the role on many structures appears once. Each entry carries the user's details, the total number of structures they hold the role on, and a sample of those structures.

Call it to audit a role before you change its permission set, or to reconcile role membership against an external system of record.

Requirements

• Mitti Premium Plan or Enterprise Plan
• "Platform management: Permissions" permission

Paginate and filter

• page_size returns up to 1000 users. The default is 1000.
• offset skips the given number of results. Advance it to page through.
• sort_direction orders the results ascending or descending.
• filter.query matches on a user's given name, family name, or email, and supports partial matches.
• filter.user_status includes or excludes inactive users.

The response returns total_count, the number of distinct users assigned to the role, and offset, the offset you requested.

Sample a user's structures

By default, each entry returns no structures. Set max_structures_per_user to a value between 1 and 50 to include a sample.

The cap applies per structure type, not across the whole entry. A value of 5 returns up to 5 structures of each type the user holds the role on, so every type the user belongs to is represented in assigned_structure_details.

Two counts are never capped, so they stay accurate when the sample is truncated:

• total_structure_count is the total number of structures the user holds the role on.
• total_structure_count_by_type_id breaks that total down by structure type. Use it to render an accurate overflow such as "+12 more" for each type. A missing key means the user holds the role on no structure of that type.

📕

Omitting max_structures_per_user samples no structures at all. It does not mean "return everything". Set it explicitly when you need assigned_structure_details populated.

📘

Use total_structure_count and total_structure_count_by_type_id for counting, never the length of assigned_structure_details. That list is a sample, so its length understates the truth whenever a type is capped.