# Pagination, Filtering & Sorting

All list endpoints in the FairePlace API support pagination, filtering, and sorting with a consistent interface.

## Pagination

### Request parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `page` | integer | `1` | Page number (1-based) |
| `per_page` | integer | `20` | Items per page (max 100) |

```bash
curl "https://api.faireplace.com/api/leases?page=2&per_page=50" \
  -H "Authorization: Bearer $API_KEY"
```

### Response format

Every paginated response includes a `meta.pagination` object:

```json
{
  "data": [...],
  "meta": {
    "pagination": {
      "current_page": 2,
      "per_page": 50,
      "total": 150,
      "total_pages": 3,
      "has_next": true,
      "has_prev": true
    }
  }
}
```

| Field | Description |
|-------|-------------|
| `current_page` | The current page number |
| `per_page` | Number of items per page |
| `total` | Total number of items across all pages |
| `total_pages` | Total number of pages |
| `has_next` | Whether there are more pages after this one |
| `has_prev` | Whether there are pages before this one |

### Iterating through all pages

```javascript
async function fetchAll(endpoint) {
  let page = 1;
  let allData = [];

  while (true) {
    const response = await fetch(
      `https://api.faireplace.com/api/${endpoint}?page=${page}&per_page=100`,
      { headers: { Authorization: `Bearer ${TOKEN}` } }
    );
    const result = await response.json();
    allData.push(...result.data);

    if (!result.meta.pagination.has_next) break;
    page++;
  }

  return allData;
}
```

## Filtering

Filter results using query parameters. Available filters vary by resource.

```bash
# Filter leases by status
curl "https://api.faireplace.com/api/leases?status=Active" \
  -H "Authorization: Bearer $API_KEY"

# Filter estates by minimum area
curl "https://api.faireplace.com/api/places/{place_id}/estates?area_min=30" \
  -H "Authorization: Bearer $API_KEY"

# Search contacts by name
curl "https://api.faireplace.com/api/contacts?search=dupont" \
  -H "Authorization: Bearer $API_KEY"
```

### Common filters

| Resource | Filters |
|----------|---------|
| Leases | `status`, `estate_id`, `start_date_from`, `start_date_to` |
| Places | `owner_id`, `postal_code`, `city`, `place_category` |
| Estates | `area_min`, `area_max`, `floor`, `number_of_room` |
| Lessees | `search`, `category` |
| Owners | `search`, `owner_category` |
| Contacts | `search`, `type` |

### Date range filtering

Use `_from` and `_to` suffixes for date ranges:

```bash
# Leases starting in 2026
curl "https://api.faireplace.com/api/leases?start_date_from=2026-01-01&start_date_to=2026-12-31" \
  -H "Authorization: Bearer $API_KEY"
```

## Sorting

Sort results using the `sort` parameter. Prefix with `-` for descending order.

```bash
# Sort by creation date (newest first)
curl "https://api.faireplace.com/api/leases?sort=-created_at" \
  -H "Authorization: Bearer $API_KEY"

# Sort by rent amount (lowest first)
curl "https://api.faireplace.com/api/leases?sort=rent_amount" \
  -H "Authorization: Bearer $API_KEY"

# Sort by last name (alphabetical)
curl "https://api.faireplace.com/api/lessees?sort=last_name" \
  -H "Authorization: Bearer $API_KEY"
```

### Sortable fields

Most resources support sorting on:
- `created_at` / `-created_at`
- `updated_at` / `-updated_at`
- Resource-specific fields (e.g., `rent_amount`, `last_name`, `area`)

## Combining parameters

Pagination, filtering, and sorting can be combined:

```bash
# Active leases, sorted by rent (highest first), page 1 of 20
curl "https://api.faireplace.com/api/leases?status=Active&sort=-rent_amount&page=1&per_page=20" \
  -H "Authorization: Bearer $API_KEY"
```

## Rate limits

List endpoints are subject to the standard rate limit of **1,000 requests per hour** per tenant. Large `per_page` values do not count as multiple requests.

Rate limit headers are included in every response:

| Header | Description |
|--------|-------------|
| `X-RateLimit-Limit` | Maximum requests per hour |
| `X-RateLimit-Remaining` | Requests remaining in the window |
| `X-RateLimit-Reset` | Unix timestamp when the limit resets |

---

## Related

- **[Error Handling](/core/errors)** — Error codes and troubleshooting
- **[Authentication](/quickstart/authentication)** — API keys and permissions
- **[Multi-tenancy](/core/multi-tenancy)** — Data isolation