List Organization Groups

Before You Begin

🔗 Use the GraphQL Playground to execute the queries in this guide.

➡️ New to GraphQL? Learn how to navigate the Playground with our Playground Basics Guide.

Prerequisites

1. Authentication: Use a Service Account token (Personal Access Tokens are deprecated).
2. Permissions: Your token must have permission to read the organization's groups.
3. Organization UUID: Identify the organization whose groups you want to list.

Step 1: Find Your Organization UUID

• Check on our Get resource IDs page for how to retrieve resource identifiers.

Step 2: List the Groups

The groups query returns a paginated connection of the groups that belong to an organization.

query {
  groups(organizationUuid: "organization-uuid-here", first: 10) {
    edges {
      node {
        id
        uuid
        name
        description
        provisioned
        canBeManaged
        totalUsers
        createdAt
        updatedAt
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
    totalCount
  }
}

Arguments

• organizationUuid (ID!, required): the organization whose groups you want to list.
• search (String, optional): filter the results by group name (case-insensitive partial match). See Step 3.
• Standard connection arguments (first, after, last, before) control pagination.

Sample response

{
  "data": {
    "groups": {
      "edges": [
        {
          "node": {
            "id": "123",
            "uuid": "group-uuid-here",
            "name": "Finance",
            "description": "Finance team members",
            "provisioned": false,
            "canBeManaged": true,
            "totalUsers": 8,
            "createdAt": "2026-01-15T12:00:00Z",
            "updatedAt": "2026-06-01T09:30:00Z"
          }
        }
      ],
      "pageInfo": {
        "hasNextPage": false,
        "endCursor": "Mg"
      },
      "totalCount": 1
    }
  }
}

Step 3: Filter Groups by Name

Pass the search argument to return only the groups whose name matches the term. The match is
case-insensitive and partial, so "fin" matches "Finance".

query {
  groups(organizationUuid: "organization-uuid-here", search: "fin", first: 10) {
    edges {
      node {
        uuid
        name
      }
    }
    totalCount
  }
}

Omitting search (or passing an empty value) returns all of the organization's groups.

Key Notes

• Permissions: requesting groups without read permission on the organization returns a Permission denied error; an unknown organizationUuid returns a not-found error.
• totalUsers: this field counts the members of each group and is resolved per group. Request it only when you need it.
• canBeManaged: reflects whether the requesting user can manage the specific group.
• Pagination: totalCount reports the full count regardless of the first/after window, so use it together with pageInfo to page through large organizations.