NYYU Logo
APIUser

Get Paginated Users

Retrieve a paginated list of users with flexible filtering and sorting options for admin dashboards

ADMIN ONLY

Get Paginated Users

Retrieve a paginated list of users with advanced filtering, sorting, and search capabilities for administrative dashboards.

Admin Access Required

This query requires ROLE_ADMIN privileges for accessing user management data.

Overview

The getPaginatedUsers query enables administrators to retrieve user lists with pagination, sorting, and filtering capabilities. Ideal for user management dashboards, analytics, and administrative interfaces.


GraphQL Schema

query {
  getPaginatedUsers(
    offset: Int!
    limit: Int!
    sortBy: String
    order: String
    filter: String
  ): PaginatedUsersResponse
}

type PaginatedUsersResponse {
  users: [User]
  totalCount: Int
  hasMore: Boolean
}

Parameters

offset

Required

Int

Number of records to skip. Use 0 for first page. Formula: offset = pageNumber × limit

limit

Required

Int

Maximum number of users per page. Recommended: 10-100 for optimal performance.

sortBy

Optional

String

Field to sort by: "id", "email", "name", "regDate", "tierLevel", "lastLoginDate"

order

Optional

String

Sort order: "ASC" (ascending) or "DESC" (descending). Default: "DESC"

filter

Optional

String (JSON)

JSON string for filtering users by email, role, country, or verification status.


Return Value

PaginatedUsersResponse

Returns a paginated response with user array, total count, and pagination metadata.

Response Fields:
users: [User] - Array of user objects
totalCount: Int - Total users matching filter
hasMore: Boolean - Whether more pages exist

Example Usage

Basic Pagination

query GetUsers {
  getPaginatedUsers(offset: 0, limit: 20) {
    users {
      id
      email
      name
      role
      tierLevel
      regDate
    }
    totalCount
    hasMore
  }
}

With Sorting

query GetRecentUsers {
  getPaginatedUsers(
    offset: 0
    limit: 50
    sortBy: "regDate"
    order: "DESC"
  ) {
    users {
      id
      email
      name
      regDate
      lastLoginDate
    }
    totalCount
  }
}

With Filtering

query GetAdminUsers {
  getPaginatedUsers(
    offset: 0
    limit: 25
    filter: "{\"role\":\"ROLE_ADMIN\",\"country\":\"USA\"}"
  ) {
    users {
      id
      email
      name
      country
      role
    }
    totalCount
  }
}

Response Example

{
  "data": {
    "getPaginatedUsers": {
      "users": [
        {
          "id": 12345,
          "email": "admin@example.com",
          "name": "Admin User",
          "role": ["ROLE_ADMIN"],
          "tierLevel": 5,
          "regDate": 1704067200
        },
        {
          "id": 12346,
          "email": "user@example.com",
          "name": "Regular User",
          "role": ["ROLE_USER"],
          "tierLevel": 2,
          "regDate": 1704153600
        }
      ],
      "totalCount": 1247,
      "hasMore": true
    }
  }
}

Pagination Info

Showing 20 users from a total of 1,247 users. More pages available.


Implementation Example

TypeScript with React Hook

import { useState, useEffect } from 'react';
import { useQuery } from '@apollo/client';
import { gql } from 'graphql-tag';

const GET_PAGINATED_USERS = gql`
  query GetPaginatedUsers(
    $offset: Int!
    $limit: Int!
    $sortBy: String
    $order: String
    $filter: String
  ) {
    getPaginatedUsers(
      offset: $offset
      limit: $limit
      sortBy: $sortBy
      order: $order
      filter: $filter
    ) {
      users {
        id
        email
        name
        role
        tierLevel
        regDate
      }
      totalCount
      hasMore
    }
  }
`;

function UserManagementTable() {
  const [page, setPage] = useState(0);
  const [pageSize, setPageSize] = useState(20);

  const { data, loading, error } = useQuery(GET_PAGINATED_USERS, {
    variables: {
      offset: page * pageSize,
      limit: pageSize,
      sortBy: 'regDate',
      order: 'DESC'
    }
  });

  if (loading) return <div>Loading users...</div>;
  if (error) return <div>Error: {error.message}</div>;

  const { users, totalCount, hasMore } = data.getPaginatedUsers;
  const totalPages = Math.ceil(totalCount / pageSize);

  return (
    <div>
      <table>
        <thead>
          <tr>
            <th>ID</th>
            <th>Email</th>
            <th>Name</th>
            <th>Role</th>
            <th>Tier</th>
          </tr>
        </thead>
        <tbody>
          {users.map(user => (
            <tr key={user.id}>
              <td>{user.id}</td>
              <td>{user.email}</td>
              <td>{user.name}</td>
              <td>{user.role.join(', ')}</td>
              <td>{user.tierLevel}</td>
            </tr>
          ))}
        </tbody>
      </table>

      <div className="pagination">
        <button
          onClick={() => setPage(p => Math.max(0, p - 1))}
          disabled={page === 0}
        >
          Previous
        </button>
        <span>Page {page + 1} of {totalPages}</span>
        <button
          onClick={() => setPage(p => p + 1)}
          disabled={!hasMore}
        >
          Next
        </button>
      </div>
    </div>
  );
}

Use Cases

⚙️

Admin Dashboard

Display user lists in admin panels with pagination, sorting, and filtering capabilities for efficient management

📊

User Analytics

Generate reports and analytics by filtering users based on tier, country, or verification status

🔍

User Search

Implement search functionality to find specific users by email, name, or other criteria

📈

Growth Tracking

Monitor user registration trends and growth patterns over time with date-based sorting


Best Practices

📏 Optimal Page Size

Use page sizes between 10-100 for best performance. Larger pages may cause timeouts.

💾 Caching Strategy

Implement client-side caching to reduce API calls when navigating between pages

🔐 Data Protection

Only request fields you need. Avoid fetching sensitive data unless necessary

⚡ Performance

Use indexes on sortBy fields and optimize filters for faster query execution