--- title: Paging slug: paging docTags: createdAt: 2024-04-29T11:00:45.862Z --- All Altrata GraphQL APIs use a common pagination methodology. If a query supports pagination, then you will only receive a subset of the results on that particular page. However, all results will be available to you even if they are not returned upfront, you will simply need to go through each of the results pages to acquire all of the data. ## How it works If a query supports pagination, then you will only retrieve a certain amount of results per page. Each Altrata API has different page limits and default page sizes. Refer to the specific API documentation to find these limits. If data is residing on another page, you will be returned a cursor value as part of your response so that it can be used to access the other pages. ## Finding Page Information To get a cursor value returned to you, will need to add the `pageInfoResponse` as a subfield within the response structure. You will also need to add the following subfields of pageInfoResponse: - `totalCount`**:** Represent the total count of items that match the search criteria - `pageInfo`**:** It further nests additional pagination-related details: - `hasNextPage`**:** Boolean indicating whether there are more pages of results available after the current page. - `startCursor`**:** Cursor pointing to the start of the current page. - `endCursor`**:** Cursor pointing to the next page of results. **Example query:** ```graphql query PersonPaginationExample { personKeywordSearch(filter: {searchKeyword: "Bill Gates"}) { items { firstName lastName } pageInfoResponse { totalCount pageInfo { hasNextPage startCursor endCursor } } } } ``` **Example response:** ```graphql { "data": { "personKeywordSearch": { "items": [ { "firstName": "William Gates", "lastName": "Gates" } ], "pageInfoResponse": { "totalCount": 47, "pageInfo": { "hasNextPage": true, "startCursor": null, "endCursor": "ALTPTR10" } } } } } ``` :::hint{type="info"} **The example response has been shortened in this guide, exact response will be longer if you run the query yourself** ::: The `pageInfoResponse` results has informed us that the total amount of results returned for the query we ran is 47, however, not all results are on this page which is why `hasNextPage` has returned a boolean value of true, and `endCursor` has provided a string that will allow us to access the next page of results. To access the next page of results, we will need to add the `pageInfo` object to our argument and supply value returned in `endCursor` as a value. ## Performing Pagination To access the next page of results you will need to add the pageInfo to your argument and one of two subfields. The pageInfo object supports two subfields that will take a cursor value as its input: - `after`**:** Fetches items after the specified cursor - `before`**:** Fetches items before the specified cursor Therefore, to access the next page, you will need to use the `after` subfield. Example query: ```graphql query PersonPaginationExample { personKeywordSearch( filter: {searchKeyword: "Bill Gates"} pageInfo: {after: "ALTPTR10"} ) { items { firstName lastName } pageInfoResponse { totalCount pageInfo { hasNextPage hasPreviousPage startCursor endCursor } } } } ``` Example response: ```graphql { "data": { "personKeywordSearch": { "items": [ { "firstName": "William Gates", "lastName": "Gates" } ], "pageInfoResponse": { "totalCount": 47, "pageInfo": { "hasNextPage": true, "hasPreviousPage": true, "startCursor": "ALTPTR0", "endCursor": "ALTPTR20" } } } } } ``` As you can see in the above example response, we have returned the next page of results. We can tell because the `hasPreviousPage` subfield has returned a value of true, and startCursor has returned the previous page cursor value. You will be able to continue looping through the results with the cursor until you have reached the last page of results. ## Limiting results As well as being able to move between pages, you will also be able to limit the results you get returned back to you in a page. To do this you can utilise the `first` and `last` properties. - `first`**: **Fetches the first 'n' elements in the list. - Example: Only return the first 10 items - `Last`**:** Fetches the last 'n' elements in the list - Example: Return the last 3 items of the results on a particular page ### First **Example of first 2 elements:** ```graphql query PersonPaginationExample { personKeywordSearch( filter: {searchKeyword: "Bill Gates"} pageInfo: {after: "ALTPTR10", first: 2} ) { items { firstName lastName } pageInfoResponse { totalCount pageInfo { hasNextPage hasPreviousPage startCursor endCursor } } } } ``` **Example of first 2 response:** ```graphql { "data": { "personKeywordSearch": { "items": [ { "firstName": "William", "lastName": "Gates" }, { "firstName": "William", "lastName": "Gates" } ], "pageInfoResponse": { "totalCount": 47, "pageInfo": { "hasNextPage": true, "hasPreviousPage": true, "startCursor": "ALTPTR8", "endCursor": "ALTPTR12" } } } } } ``` As you can see in the example response, only two items have been returned per page. ### Last The `first` field returned the first items per page, the `last` field will return the last items per page. Imagine that the results are in an array. The last field will loop backwards in that array and only return the specified amount of items in the array. **Example:** Imagine we had an array that held 5 values: \[1, 2, 3, 4, 5]. If we specified that we wanted only the last 2 elements to be returned, then only values 5 and 4 would be returned to us. This is how the last field will work in GraphQL. When using the `last` field, it is mandatory that you use the `before` field in conjunction with it. **Example of last 2 elements query:** ```graphql query PersonPaginationExample { personKeywordSearch( filter: {searchKeyword: "Bill Gates"} pageInfo: {before: "ALTPTR10", last: 2} ) { items { firstName lastName } pageInfoResponse { totalCount pageInfo { hasNextPage hasPreviousPage startCursor endCursor } } } } ``` If you use the `after` field with `last` field instead of the `before` field, you will see the following error: ```graphql { "data": { "personKeywordSearch": null }, "errors": [ { "path": [ "personKeywordSearch" ], "data": null, "errorType": "Error", "errorInfo": null, "locations": [ { "line": 2, "column": 3, "sourceName": null } ], "message": "Missing mandatory field 'before' @ persons" } ] } ``` ## Result Limits | API | Query or field | Limit | | ---------------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | | Profile API | Default page size for paged queries | 10 items (set first to change) | | Profile API | personBulkIDSearch, organizationBulkIDSearch | Up to 100 IDs per request | | Profile API | personSearch, organizationSearch | Up to 10,000 results per query | | Profile API | Role lists inside organizationIDSearch, organizationBulkIDSearch and organizationKeywordSearch | Up to 50 roles per list; use the paged rolesEmployment, rolesBoard or rolesCommittee queries for the full list | | Relationship API | Page size | Up to 500 results per page |