Skip to main content

List groups

GET 
/groups

Returns one page of the groups in your tenant, in the order the directory hands them back.

Groups are how access is granted to more than one person at a time: a permission set assigned to a group is held by everyone in it. That makes the membership operations in this section changes to real AWS access, not bookkeeping.

The items are summaries, not groups. Each entry carries an id and a name and nothing else. This is not the same object GET /groups/{groupName} returns: that operation answers with the directory's own representation of the group, a larger object with more fields. Fetch a group individually when you need anything beyond the two fields here.

The wrapper around the array carries seven keys: the array itself, the four pagination counters, count for the number of items actually in this page, and realm identifying the tenant the path resolved to. It does not carry customerId, which the otherwise similar wrapper on GET /users does. The two look alike enough that it is worth checking before reading a field across both.

Watch the pageSize limit. The largest page this endpoint will serve is 1000, and an out-of-range value is not trimmed to the maximum; it resets to the default of 25. Asking for pageSize=5000 therefore returns 25 groups, not 1000, with pageSize: 25 in the body and no warning anywhere. The same reset applies to pageSize=0, to negatives, and to anything that is not a number. Read pageSize back from the response whenever you did not send a value you are certain of.

One reporting caveat: if the count query behind total fails, Prism falls back to the number of rows on this page and still answers 200. A total that exactly equals count on a full page is worth a second look.

Request​

Responses​

One page of group summaries. A page past the end of the list, and a tenant with no groups at all, are both a 200 with an empty groups array.