> ## Documentation Index
> Fetch the complete documentation index at: https://api.jobaffinity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pagination

> Understanding and managing collection pagination

## Pagination Principle

Resources returning many results are automatically paginated to optimize performance.

## Using the `_next` Field

The `_next` field in the response contains the URL of the next page.

### Paginated Response Example

```json theme={null}
{
  "_status": "OK",
  "_self": "/restapi/v1/job",
  "_schema": "/restapi/schemav1/jobs",
  "_next": "/restapi/v1/job?pagecursor=42",
  "items": [
    {
      "id": 1,
      "title": "Full-Stack Developer",
      "_self": "/restapi/v1/job/1"
    },
    {
      "id": 2,
      "title": "Project Manager",
      "_self": "/restapi/v1/job/2"
    }
  ]
}
```

## Iterating Through All Pages

### Basic Algorithm

1. Make the first request
2. Process the `items` from the page
3. Check if `_next` is present and not empty
4. If yes, request `_next` and return to step 2
5. If no, all pages have been retrieved

### Python Example

```python theme={null}
import requests

def fetch_all_pages(url, auth):
    """Fetches all items from a paginated resource"""
    all_items = []

    while url:
        response = requests.get(url, auth=auth)
        data = response.json()

        if data.get('_status') != 'OK':
            break

        all_items.extend(data.get('items', []))
        url = data.get('_next', '')

    return all_items

# Usage
jobs = fetch_all_pages(
    'https://jobaffinity.fr/restapi/v1/job',
    auth=('login', 'password')
)
```

### Shell Example

```bash theme={null}
#!/bin/bash

URL="https://jobaffinity.fr/restapi/v1/job"
AUTH="login:password"

while [ ! -z "$URL" ]; do
  RESPONSE=$(curl -s --basic --user "$AUTH" "$URL")

  # Process items
  echo "$RESPONSE" | jq '.items[]'

  # Get next URL
  URL=$(echo "$RESPONSE" | jq -r '._next // empty')
done
```

## Paginated Resources

The following resources are paginated:

* Job collection (`/restapi/v1/job`)
* Candidate collection (`/restapi/v1/candidate`)
* Job applications collection (`/restapi/v1/job/{id}/application`)
* Candidate applications collection (`/restapi/v1/candidate/{id}/application`)
* Step changes collection (`/restapi/v1/step`)
* Notes collection (`/restapi/v1/note`)
* Webhook history (`/restapi/v1/webhook/task`)

## Non-Paginated Resources

Some resources return all data in a single response:

* Job details (`/restapi/v1/job/{id}`)
* Candidate details (`/restapi/v1/candidate/{id}`)
* Application details (`/restapi/v1/application/{id}`)
* Job team (`/restapi/v1/job/{id}/team`)
* Process list (`/restapi/v1/process`)

<Tip>
  Don't try to guess page sizes or manipulate the pagination cursor. Always use the URL provided by `_next`.
</Tip>