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

# Pagination and filtering

> Working with list endpoints: pagination, filters, ordering and search.

## Pagination

List endpoints return a paginated payload:

```json theme={null}
{
  "count": 142,
  "next": "https://api.piriod.com/customers/?page=2",
  "previous": null,
  "results": [
    /* items of the current page */
  ]
}
```

Control pagination with query parameters:

| Parameter   | Type    | Default | Notes                       |
| ----------- | ------- | ------- | --------------------------- |
| `page`      | integer | `1`     | 1-indexed page number.      |
| `page_size` | integer | `20`    | Items per page (max `100`). |

```bash theme={null}
curl "https://api.piriod.com/customers/?page=2&page_size=50" \
  -H "Authorization: Token sk_live_xxxxx" \
  -H "x-simple-workspace: acc_..."
```

## Filtering

Filters are exposed as query parameters. Each list endpoint declares the
filterable fields in the API Reference (see the Parameters tab). For example,
`GET /customers/` accepts `country`, `email`, `name`, `tax_id`, `created`,
`subscriptions`, `sources`.

Common patterns:

```bash theme={null}
# exact match
?status=active

# range (date or numeric fields)
?created__gte=2026-01-01&created__lte=2026-01-31

# membership
?status__in=draft,finalized

# nested foreign keys
?customer=cus_01H8XYZ123ABC
```

### Filtering by metadata

Resources that expose a `metadata` field accept arbitrary filters using the
`metadata__<key>` pattern:

```bash theme={null}
?metadata__order_id=12345
```

## Ordering

Use `ordering` to sort the results. Prefix the field name with `-` for
descending order:

```bash theme={null}
?ordering=name
?ordering=-created
```

Each list endpoint declares its supported ordering fields.

## Search

Some endpoints expose `search` for free-text matching across configured fields:

```bash theme={null}
?search=acme
```