Cursor-based pagination uses markers called cursors to go through the results. It's the fastest and most reliable way to handle a large number of items.

Bob’s cursor-based endpoints accept the cursor and limit query parameters. A cursor is a marker indicating the next page’s first item. By specifying the limit, you can control the number of entities returned per page. The maximum limit value is 200.

Pagination parameters:

Endpoints that support pagination

The following endpoints support pagination:

• GET List work history for a list of employees
• GET List the lifecycle history for a list of employees.
• GET List employment history for a list of employees.
• GET List payroll history (salaries) for a list of employees.

How to use cursor pagination

1. Call the API first time: do not pass the cursor parameter.
2. Extract the next_cursor value from the response body:
   • If null: there are no more results.
   • If has a value: this value should be passed as the cursor for the next call to request the next page of results.
3. Call the API again: to ensure consistent results, make sure you are using exactly the same filtering parameters as the call that returned the cursor, and that you do not change the service user’s permissions during an ongoing API call.

Examples

Read operations in Bob may be implemented as GET or POST (for 'search' queries) endpoints. The following examples demonstrate how to send the pagination parameters in both cases.

GET endpoint call with pagination

GET /items?cursor=rfJhY3Rpdml09d34JDE&limit=50
	//do not pass `cursor` in 1st call
	//cursor must be URL encoded

Response: {
  "results": {},// the returned data
  "response_metadata": {
    "next_cursor": "rfJhY3Rpdml09d3827" // cursor for the next call  
  }  
}

Note: The cursor value returned in the response is a string that may contain characters that need to be replaced when sending them as a query parameter in the URL. For example, :: should become %3A%3A. Make sure to perform URL encoding on the next-cursor before you send it as a query parameter.

POST (search) endpoint call with pagination

POST /items/search  
Request:  
{
  "pagination":  {
    "limit": 50,
    "cursor": "rfJhY3Rpdml09d34JDE" //do not pass `cursor` in 1st call  
  }
}

Response: 
{
  "results": [],
   "response_metadata": {
     "next_cursor": "rfJhY3Rpdml09d3827" // cursor for the next call  
  }  
}