# Pagination and filtering

> Page, scope, filter, and sort parameters on list endpoints.

## Pagination

Company and opportunity lists are paginated:

| Parameter | Default | Description |
|---|---|---|
| `page` | `1` | Page number. |
| `per` | `40` | Rows per page (10–100). |

The response includes `rows`, `total` (the filtered total), `page`, and `pages`:

```json
{ "ok": true, "rows": [ … ], "total": 21, "page": 1, "pages": 3 }
```

To fetch every record, increment `page` until it reaches `pages`:

```python
def all_companies(session):
    page = 1
    while True:
        j = session.get("https://ornek.solk.app/api/v1/customers",
                        params={"scope": "all", "per": 100, "page": page}).json()
        yield from j["rows"]
        if page >= j["pages"]:
            break
        page += 1
```

People, action, fair lead, and email thread lists are not paginated; they return at most 300 records, all open actions, 300 records, and 100 records, respectively. Use filters to narrow the results.

## Scope

Most lists accept `scope`:

| Value | Result |
|---|---|
| `mine` | Records you own (default for the sales role) |
| `all` | All records you're allowed to see (default for the admin role) |
| `<user ID>` | That user's records |

Scope does **not** expand visibility: in an installation with team visibility enabled, `scope=all` returns only your own team's records. See [Users and roles](/users-and-roles).

## Filters and sorting

| Endpoint | Filters | Sort (`sort`) |
|---|---|---|
| [Companies](/rest-api/companies/list) | `q`, `status`, `city`, `visit`, `risk`, `active` | `name`, `visit`, `priority` |
| [Opportunities](/rest-api/deals/list) | `q`, `stage` (`open`, `closed`, `account`, a stage key) | `update`, `health`, `value`, `sla` |
| [People](/rest-api/people/list) | `q`, `former` | name |
| [Actions](/rest-api/actions/list) | `state` (`today`, `overdue`, `soon`, `open`, `week`), `customer_id` | due date |
| [Calendar](/rest-api/calendar/list) | `from`, `to`, `done` | start time |
| [Fair leads](/rest-api/fairs/leads-list) | `q`, `interest`, `owner` | newest first |
| [Threads](/rest-api/email/threads-list) | `kind` + `id`, or `filter`, `q` | by latest message |

The `q` text search is case-insensitive and matches anywhere in the field.

## Fetching changes

There is no separate "changes" endpoint. To sync:

- Fetch opportunities with `sort=update` and stop based on the `last_update` field.
- To learn about new and changed records immediately, use [webhooks](/guides/webhooks).