List Users

Retrieve lists of users in organizations or projects with filtering and pagination.

List Users

Blue provides multiple queries to list users at different scopes - organization-wide, project-specific, or individual user lookup. These queries support pagination, filtering, and sorting to efficiently manage large user bases.

Basic Example - Organization Users

List all users in an organization:

query ListCompanyUsers {
  companyUserList(companyId: "acme-corp") {
    users {
      id
      email
      fullName
      jobTitle
      lastActiveAt
    }
    pageInfo {
      totalItems
      hasNextPage
    }
  }
}

Advanced Example - Filtered Project Users

List project users with search and pagination:

query ListProjectUsers {
  projectUserList(
    projectId: "web-redesign"
    search: "engineer"
    first: 20
    orderBy: lastActiveAt_DESC
  ) {
    edges {
      node {
        id
        email
        fullName
        accessLevel
        customRole {
          id
          name
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Available Queries

companyUserList

Lists all users in an organization with optional filtering.

Input Parameters

ParameterTypeRequiredDescription
companyIdString!✅ YesOrganization ID or slug
notInProjectIdStringNoExclude users already in this project
searchStringNoSearch by name or email
firstIntNoNumber of results to return (forward pagination)
afterStringNoCursor for forward pagination
lastIntNoNumber of results to return (backward pagination)
beforeStringNoCursor for backward pagination
skipIntNoNumber of results to skip
orderByUserOrderByInputNoSort order (see below)

projectUserList

Lists all users in a specific project.

Input Parameters

ParameterTypeRequiredDescription
projectIdString!✅ YesProject ID or slug
searchStringNoSearch by name or email
firstIntNoNumber of results (max: 200)
afterStringNoCursor for pagination
orderByUserOrderByInputNoSort order

user

Retrieves a single user by ID.

Input Parameters

ParameterTypeRequiredDescription
idString!✅ YesUser ID

Sorting Options

UserOrderByInput Values

ValueDescription
createdAt_ASCSort by registration date (oldest first)
createdAt_DESCSort by registration date (newest first)
lastActiveAt_ASCSort by last activity (oldest first)
lastActiveAt_DESCSort by last activity (newest first)
firstName_ASCSort by first name (A-Z)
firstName_DESCSort by first name (Z-A)
lastName_ASCSort by last name (A-Z)
lastName_DESCSort by last name (Z-A)
email_ASCSort by email address (A-Z)
email_DESCSort by email address (Z-A)
username_ASCSort by username (A-Z)
username_DESCSort by username (Z-A)
jobTitle_ASCSort by job title (A-Z)
jobTitle_DESCSort by job title (Z-A)

Response Fields

User Object

FieldTypeDescription
idString!Unique user identifier
uidString!Firebase authentication UID
usernameString!User’s chosen username
emailString!Email address (visible to OWNER/ADMIN only)
firstNameStringFirst name
lastNameStringLast name
fullNameStringCombined first and last name
jobTitleStringProfessional title
phoneNumberStringContact number
dateOfBirthDateTimeBirth date
isEmailVerifiedBoolean!Email verification status
lastActiveAtDateTimeLast activity timestamp
createdAtDateTime!Account creation date
updatedAtDateTime!Last profile update
isOnlineBoolean!Current online status
timezoneStringUser’s timezone
localeStringLanguage preference
themeJSONUI theme preferences
imageImageProfile picture object

Project User Additional Fields

When listing project users, additional fields are available:

FieldTypeDescription
accessLevelUserAccessLevel!User’s role in the project
customRoleProjectUserRoleCustom role details if applicable
joinedAtDateTime!When user joined the project

Pagination Info

FieldTypeDescription
totalItemsInt!Total number of users
totalPagesIntTotal pages (for offset pagination)
pageIntCurrent page number
perPageIntItems per page
hasNextPageBoolean!More results available
hasPreviousPageBoolean!Previous results available
startCursorStringFirst item cursor
endCursorStringLast item cursor

Required Permissions

QueryRequired Permission
companyUserListAny authenticated user in the organization
projectUserListAny project member (including VIEW_ONLY)
userAny authenticated user

Error Responses

Organization Not Found

{
  "errors": [{
    "message": "Organization not found",
    "extensions": {
      "code": "COMPANY_NOT_FOUND"
    }
  }]
}

Project Not Found

{
  "errors": [{
    "message": "Project not found",
    "extensions": {
      "code": "PROJECT_NOT_FOUND"
    }
  }]
}

Unauthorized Access

{
  "errors": [{
    "message": "You don't have access to this resource",
    "extensions": {
      "code": "UNAUTHORIZED"
    }
  }]
}

Important Notes

  • Performance: Use pagination for large user lists (max 200 users per request)
  • Search: Searches across first name, last name, and email fields
  • Email Privacy: Email addresses are only visible to users with OWNER or ADMIN access levels
  • Online Status: isOnline updates in real-time via WebSocket connections
  • Profile Images: Use the image.variants field for different sizes
  • Filtering: The notInProjectId parameter is useful when building user selection interfaces
  • Access Levels: Project user lists include role information not available in organization lists