Retrieve a Group, Its Owners, Users, and Available Interfaces

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

Authentication: Use a Service Account token (Personal Access Tokens are deprecated).
Permissions: Your token must have read permission on the group's resource (the organization the group belongs to).
Group UUID: Identify the group you want to inspect. Use List Organization Groups to discover group UUIDs.

Step 1: Find the Group UUID

List an organization's groups with List Organization Groups and take the uuid of the group you want.
See our Get resource IDs page for more on retrieving resource identifiers.

Step 2: Fetch a Single Group

The group query returns one group identified by its uuid.

query {
  group(uuid: "group-uuid-here") {
    id
    uuid
    name
    description
    provisioned
    createdAt
    updatedAt
  }
}

Arguments

uuid (ID!, required): the UUID of the group to fetch.

Sample response

{
  "data": {
    "group": {
      "id": "123",
      "uuid": "group-uuid-here",
      "name": "Finance",
      "description": "Finance team members",
      "provisioned": false,
      "createdAt": "2026-01-15T12:00:00Z",
      "updatedAt": "2026-06-01T09:30:00Z"
    }
  }
}

Step 3: List the Group Owners

The groupOwners query returns the group's owners together with the maximum number of owners a group may have.

query {
  groupOwners(groupUuid: "group-uuid-here") {
    owners {
      id
      email
      name
      uuid
      avatarUrl
    }
    maxAllowedOwners
  }
}

Arguments

groupUuid (ID!, required): the UUID of the group whose owners you want.

Sample response

{
  "data": {
    "groupOwners": {
      "owners": [
        {
          "id": "456",
          "email": "[email protected]",
          "name": "Ada Lovelace",
          "uuid": "user-uuid-here",
          "avatarUrl": "https://app.pipefy.com/avatar.png"
        }
      ],
      "maxAllowedOwners": 3
    }
  }
}

Step 4: List the Group Users

The groupUsers query returns a paginated connection of the users that belong to the group, including each user's role name on the group's resource.

query {
  groupUsers(groupUuid: "group-uuid-here", searchTerm: "ada", first: 10) {
    edges {
      node {
        id
        email
        name
        uuid
        avatarUrl
        roleName
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
    totalCount
  }
}

Arguments

groupUuid (ID!, required): the UUID of the group whose users you want.
searchTerm (String, optional): filter the users by name or email (case-insensitive partial match). Omit it to return every user in the group.
Standard connection arguments (first, after, last, before) control pagination.

Step 5: Find Interfaces Available to the Group

The interfacesAvailableToGroup query returns a paginated connection of the interfaces the group is not yet part of and to which the requesting user can add members, along with the roles the user can assign on each interface.

query {
  interfacesAvailableToGroup(groupUuid: "group-uuid-here", searchTerm: "sales", first: 10) {
    edges {
      node {
        availableRoles
        interface {
          id
          name
        }
      }
    }
    totalCount
  }
}

Arguments

groupUuid (ID!, required): the UUID of the group.
searchTerm (String, optional): filter the interfaces by name. Omit it to return every available interface.
Standard connection arguments (first, after, last, before) control pagination.

Key Notes

Permissions: every query in this guide requires read permission on the group's resource. Without it, the response is a Permission denied error; an unknown groupUuid/uuid returns a not-found error (Couldn't find Group with ...).
maxAllowedOwners: a group may have at most this many owners (currently 3); use it to guard owner-assignment flows.
availableRoles: reflects the roles the requesting user is allowed to grant on that interface, so it varies per user.
Pagination: groupUsers and interfacesAvailableToGroup are connections, so totalCount reports the full count regardless of the first/after window; pair it with pageInfo to page through large groups.