python-gitlab
diff --git a/‎docs/api-usage.rst‎
Lines changed: 11 additions & 2 deletions b/‎docs/api-usage.rst‎
Lines changed: 11 additions & 2 deletions
diff --git a/‎gitlab/base.py‎
Lines changed: 2 additions & 2 deletions b/‎gitlab/base.py‎
Lines changed: 2 additions & 2 deletions
diff --git a/‎gitlab/client.py‎
Lines changed: 12 additions & 6 deletions b/‎gitlab/client.py‎
Lines changed: 12 additions & 6 deletions
@@ -265,8 +265,17 @@ The generator exposes extra listing information as received from the server:
 * ``prev_page``: if ``None`` the current page is the first one
 * ``next_page``: if ``None`` the current page is the last one
 * ``per_page``: number of items per page
-* ``total_pages``: total number of pages available
-* ``total``: total number of items in the list
+* ``total_pages``: total number of pages available. This may be a ``None`` value.
+* ``total``: total number of items in the list. This may be a ``None`` value.
+
+.. note::
+
+   ``total_pages`` and ``total`` may have a value of ``None``. For performance
+   reasons, if a query returns more than 10,000 records, GitLab doesn’t return
+   any value for ``total_pages`` or ``total``.
+
+   For more information see:
+   https://docs.gitlab.com/ee/user/gitlab_com/index.html#pagination-response-headers
 
 Sudo
 ====
 
@@ -288,12 +288,12 @@ def per_page(self) -> int:
         return self._list.per_page
 
     @property
-    def total_pages(self) -> int:
+    def total_pages(self) -> Optional[int]:
         """The total number of pages."""
         return self._list.total_pages
 
     @property
-    def total(self) -> int:
+    def total(self) -> Optional[int]:
         """The total number of items."""
         return self._list.total
 
 
@@ -966,17 +966,23 @@ def per_page(self) -> int:
         return int(self._per_page)
 
     @property
-    def total_pages(self) -> int:
+    def total_pages(self) -> Optional[int]:
         """The total number of pages."""
-        if TYPE_CHECKING:
-            assert self._total_pages is not None
+        if self._total_pages is None:
+            # NOTE(jlvillal): When a query returns more than 10,000 items GitLab doesn't
+            # return the header for this value. So we return None.
+            # https://docs.gitlab.com/ee/user/gitlab_com/index.html#pagination-response-headers
+            return None
         return int(self._total_pages)
 
     @property
-    def total(self) -> int:
+    def total(self) -> Optional[int]:
         """The total number of items."""
-        if TYPE_CHECKING:
-            assert self._total is not None
+        if self._total is None:
+            # NOTE(jlvillal): When a query returns more than 10,000 items GitLab doesn't
+            # return the header for this value. So we return None.
+            # https://docs.gitlab.com/ee/user/gitlab_com/index.html#pagination-response-headers
+            return None
         return int(self._total)
 
     def __iter__(self) -> "GitlabList":