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

# Pagination, filtering, and sorting

> How to paginate, sort, and filter collections consistently.

# Pagination, filtering, and sorting

## Pagination, filtering and sorting

### Pagination

#### Page pagination

Use `page` and `limit`:

```http theme={null}
GET /users?page=2&limit=50
```

Example response snippet:

```json theme={null}
{
  "pagination": {
    "page": 2,
    "page_size": 50,
    "has_more": true,
    "total_pages": 10
  }
}
```

#### Offset pagination

Use `offset` and `limit`:

```http theme={null}
GET /users?offset=100&limit=50
```

Example response snippet:

```json theme={null}
{
  "pagination": {
    "offset": 100,
    "limit": 50,
    "has_more": true,
    "total": 500
  }
}
```

#### Cursor pagination

```http theme={null}
GET /users?cursor=base64EncodedCursor&limit=100
```

Example response snippet:

```json theme={null}
{
  "pagination": {
    "limit": 100,
    "current_cursor": "base64EncodedCursor",
    "next_cursor": "anotherBase64EncodedCursor",
    "has_more": true
  }
}
```

### Sorting

Use '+' (ASC) or '-' (DESC) as a prefix for each field. If not specified, default is ASC. Multiple fields can be separated by a comma.

```http theme={null}
GET /users?order_by=+id,-price
```

In Apivalk, this `order_by` parameter automatically populates the `sorting()` bag on the request object, based on the fields allowed in the `Route` definition. Any field not declared via `Route::sorting([...])` (or `AbstractResource::availableSortings()`) is rejected by the validation middleware with a `422`.

### Filtering

Filtering allows clients to narrow down results by specifying conditions on fields using flat key-value parameters.

Example: retrieve all plugs with phase AC:

```http theme={null}
GET /plugs?phase=AC
```

Filters may also use parameter names that are not directly bound to object fields.

Example:

```http theme={null}
GET /orders?min_price=200
```