# Queries and paging

List endpoints accept an [OData](https://www.odata.org/)-style subset: **`$filter`, `$search`, `$orderby`**, and paging with **`$skip`** and **`$count`**. Queries run against a search index of list items (`ApiListItem`); each type — `CalculationListItem`, `EmploymentListItem` — customises its `data` and `status`.

Examples use the **test** environment; see [Environments](https://code.salaxy.com/get-started/environments.md) for demo and production.

## The result

```json
{
  "items": [
    { "id": "f2b9…", "status": "paymentStarted", "updatedAt": "2026-10-15T08:12:00Z" }
  ],
  "nextPageLink": "https://test-secure.salaxy.com/v03/api/calculations?%24skip=50",
  "count": 123
}
```

- `items` — at most **50** list items per page.
- `nextPageLink` — present when there are more. **Follow it until it is missing.**
- `count` — the total for the filters, only when you ask with `$count=true` (slower — use it only when needed).

**A list item is not the whole object.** When you need the full record — an employment's `info`, `work` and `contacts` — fetch it by id.

## Query options

| Option | Example |
|---|---|
| `$filter` | `$filter=status eq 'paymentStarted'` · `$filter=otherPartyInfo/officialId eq '190372-942M'` |
| `$search` | `$search='Palkkanen'` — searches the fields marked searchable. Salaxy extension: `$search=owner:…` and `$search=other:…`, which recognise a personal identity code or an id and filter on the right field |
| `$orderby` | `$orderby=otherPartyInfo/avatar/sortableName asc, updatedAt desc` — default is usually `updatedAt desc` |
| `$skip` | Paging, in steps of the page size (50; 1000 on the [Pro API](https://code.salaxy.com/integration/pro-api.md)) |
| `$count` | `$count=true` adds `count` |

## Filter operators

| Operator | Meaning | Example |
|---|---|---|
| `eq` | Equal | `$filter=status eq 'paymentSucceeded'` |
| `ne` | Not equal | `$filter=status ne 'paymentSucceeded'` |
| `gt`, `ge` | Greater than, or equal | `$filter=grossSalary ge 2000` |
| `lt`, `le` | Less than, or equal | `$filter=grossSalary le 5000` |
| `and` | Both | `$filter=salaryDate ge 2026-01-01 and salaryDate le 2026-03-31` |
| `or` | Either | `$filter=status eq 'paymentSucceeded' or status eq 'paymentStarted'` |
| `not` | Negation | `$filter=not (status eq 'paymentSucceeded')` |

The string functions `contains`, `startswith`, `endswith` and `in` are **not supported**. Use `$search` for text.

Which fields you can filter, search and sort on: [Query field reference](https://code.salaxy.com/reference/query-fields.md).

## Examples

Replace `calculations` with the list you query. Money is in euros; dates are ISO 8601.

```http
GET https://test-secure.salaxy.com/v03/api/calculations?$filter=externalId eq 'PARTNER-INV-00042'
GET https://test-secure.salaxy.com/v03/api/calculations?$filter=salaryDate ge 2026-01-01 and salaryDate le 2026-03-31
GET https://test-secure.salaxy.com/v03/api/calculations?$orderby=salaryDate desc, grossSalary desc
```

To read every page, omit `$top` and follow `nextPageLink`. It advances `$skip`:

```http
GET https://test-secure.salaxy.com/v03/api/calculations?$filter=status eq 'paymentSucceeded'
GET https://test-secure.salaxy.com/v03/api/calculations?$filter=status eq 'paymentSucceeded'&$skip=50
```

## Avoid `$top`

**`$top` suppresses `nextPageLink`**, so anything beyond that page is silently cut off. A `$top` above the page size returns `400`. To read everything, omit `$top` and follow `nextPageLink`.

`$select` is accepted but discouraged (it returns a partial object, with no field-name check); `$expand` and `$value` are not supported.

## Checklist

- Every list read follows `nextPageLink` until it is gone.
- No `$top` in a query that must return everything.
- Full records are fetched by id when list-item fields are not enough.
