---
updatedAt: 2025-09-18T23:16:06.000Z
agentTools:
  projectIndex: https://developer.personio.de/v1.0/llms.txt
---

# Pagination Adoption Guide for V1 GET employees endpoint

## Overview

To improve the performance and reliability of Personio public API the pagination for the `GET /v1/company/employees` endpoint will be enforced.

<br />

## Key Changes

* **Mandatory pagination:** All requests to `GET /v1/company/employees` must include pagination parameters using `offset` and `limit`. Unpaginated requests will default to **50 employees per page**.
* **Limit reduction:** The maximum number of employees that can be returned per request will be reduced from 200 to 100.
* **Default page size:** If no pagination parameters are provided, the response will default to 50 employees per page.

<br />

## What You Need to Do

### Update your API requests

To comply with the new pagination rules, ensure that your requests to the GET /v1/company/employees endpoint include the `offset` and `limit` parameters:

* offset: The starting position for the employee records.
* limit: The number of employee records to return, with a maximum of 100.

```
GET /v1/company/employees?offset=0&limit=100
```

If no pagination parameters are provided, the API will return **50 employees per page** by default:

```
GET /v1/company/employees
```

### Process paginated responses

The API response will include pagination details within the `metadata` field. Below is an example of the response structure you will receive:

```json JSON
{  
  "data": [  
     // Employees data  
  ],  
  "metadata": {  
    "total_elements": 100,  
    "current_page": 0,  
    "total_pages": 2  
  },  
  "offset": 0,  
  "limit": 50  
}
```

### Iterating through multiple pages

If the employee dataset spans multiple pages, you will need to adjust the `offset` to fetch subsequent pages, based on the `metadata` values returned in the response.

Sample pseudo-code for fetching all employees:

```python Python
offset = 0  
limit = 100  
employees = []  
while True:  
    response = api.get('/v1/company/employees', params={'offset': offset, 'limit': limit})  
    employees.extend(response['employees'])  
    if response['metadata']['current_page'] >= response['metadata']['total_pages'] - 1:  
        break  
    offset += limit
```

### Error handling

If a request includes a `limit` greater than 100, the API will return a 422 Unprocessable Entity error. Make sure your application handles these errors appropriately.

```json JSON
{  
    "success": false,  
    "error": {  
        "message": "The limit must be between 1 and 100.",  
        "code": 0,  
        "error_data": {  
            "limit": [  
                "The limit must be between 1 and 100."  
            ]  
        }  
    }  
}
```

<br />

## FAQ

#### Why is pagination now enforced?

Previously, it was possible to request all employees without pagination, which caused performance issues. Enforcing pagination ensures that datasets are returned in manageable chunks, improving performance and reliability.

#### What happens if I don’t include pagination parameters?

If you don’t specify pagination, the API will default to returning 50 employees per page. You can adjust this by using the offset and limit parameters.

#### Can I still request 200 employees per page?

No, the maximum limit will be been reduced from 200 to 100 to optimize performance and ensure efficient handling of high traffic.