---
updatedAt: 2026-08-13T06:27:21.000Z
---

Fetch the complete documentation index at: https://apidocs.hibob.com/llms.txt. Use this file to discover all available pages before exploring further.

# Pagination

Bob offers cursor-based pagination for some of our API’s collection endpoints.

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:

<Table>
  <thead>
    <tr>
      <th>
        parameter
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        cursor (string)
      </td>

      <td>
        A marker (an opaque string value) representing the first item on the next page of results.
      </td>
    </tr>

    <tr>
      <td>
        limit (integer)
      </td>

      <td>
        limit specifies the number of items per page, up to a maximum of 200.
        Requests exceeding this return a 400 error. If not provided, the default is 50 items.
      </td>
    </tr>
  </tbody>
</Table>

# Endpoints that support pagination

The following endpoints support pagination:

* **Employee data:**
  * [List work history for a list of employees](https://apidocs.hibob.com/reference/get_bulk-people-work)
  * [List the lifecycle history for a list of employees](https://apidocs.hibob.com/reference/get_bulk-people-lifecycle).
  * [List employment history for a list of employees](https://apidocs.hibob.com/reference/get_bulk-people-employment).
  * [List payroll history (salaries) for a list of employees](https://apidocs.hibob.com/reference/get_bulk-people-salaries).
  * [List dependents for a list of employees](https://apidocs.hibob.com/reference/get_bulk-people-dependents).
  * [List right to work entries for a list of employees](https://apidocs.hibob.com/reference/get_bulk-people-right-to-work).
  * [Search for actual payments](https://apidocs.hibob.com/reference/post_people-actual-payments-search).
* **Workforce planning:**
  * [Read company positions openings](https://apidocs.hibob.com/reference/post_positions-position-openings-search).
  * [Read company positions budgets](https://apidocs.hibob.com/reference/post_positions-position-budget-search).
* **Job catalog:**
  * [Read company job profiles](https://apidocs.hibob.com/reference/post_job-catalog-job-profiles-search)
  * [Get all job roles](https://apidocs.hibob.com/reference/get_job-catalog-job-roles)
  * [Get all job families](https://apidocs.hibob.com/reference/get_job-catalog-job-families)
  * [Get all job family groups](https://apidocs.hibob.com/reference/get_job-catalog-job-family-groups)

# Employee field reads without pagination

These endpoints return a **complete result set in one response** (no `limit`, `cursor`, or `next_cursor`):

* [Search for employees](https://apidocs.hibob.com/reference/post_people-search) — all matching employees in one `employees` array
* [Read company employee fields by employee ID](https://apidocs.hibob.com/reference/post_people-identifier) — one employee per call

See [People read API contract — Pagination and result scope](https://apidocs.hibob.com/docs/people-read-api-contract#pagination-and-result-scope). For large companies, use [client-side batching via ID discovery and `root.id` filters](https://apidocs.hibob.com/docs/people-read-api-contract#recommended-pattern-for-large-companies-client-side-batching) instead of one unfiltered search with many fields.

# 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

```javascript
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

```javascript
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  
  }  
}
```