> For the complete documentation index, see [llms.txt](https://docs.api.intratool.de/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.api.intratool.de/introduction/query-manipulation/result-control.md).

# Result Control

Result Control query parameters determine which public fields and relations the intratool API returns and how it orders, limits, or paginates the result. These controls do not bypass resource authorization, visibility, or Restricted Scope rules.

Each endpoint defines the fields, relations, computed properties, and pagination behavior it supports. Resource-specific query extensions are not part of the shared Result Control contract unless the affected API reference documents them explicitly.

## Query Parameters

| Key          | Type      | Default             | Description                                                                                                                                     |
| ------------ | --------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `select`     | `string`  | Endpoint fields     | Comma-separated fields to return.                                                                                                               |
| `with_count` | `string`  | No counts           | Pipe-separated relations whose counts are returned.                                                                                             |
| `include`    | `string`  | Endpoint relations  | Pipe-separated relations to return.                                                                                                             |
| `filter`     | `object`  | `{}`                | Standard [Value Filters](/introduction/query-manipulation/value-filters.md) and [Constraints](/introduction/query-manipulation/constraints.md). |
| `sort`       | `string`  | Endpoint order      | Comma-separated fields used for ordering.                                                                                                       |
| `limit`      | `integer` | No additional limit | Maximum number of records.                                                                                                                      |
| `page`       | `integer` | `1`                 | Page number for pagination-enabled endpoints.                                                                                                   |
| `per_page`   | `integer` | `25`                | Page size for pagination-enabled endpoints.                                                                                                     |
| `appends`    | `string`  | Endpoint appends    | Comma-separated computed fields to add.                                                                                                         |

## Includes

Use `include` to return related resources without additional API requests. The relation must be listed as public in the affected resource's Model Definition.

**Syntax**

* `{route}` - Endpoint from which records are retrieved.
* `?include` - Query parameter containing the relations.
* `{relations}` - Relation identifiers separated by `|`; use `.` for nested relations.

<mark style="color:green;">`GET`</mark> `/api/{route}?include={relations}`

### Relation Fields

Append `:` and comma-separated field keys to select fields on an included relation.

`?include={relation}:{field1},{field2}`

{% hint style="warning" %}
Include every key needed to resolve the relation. For example, a selected child record may need its primary and foreign keys for the relation to be returned correctly.
{% endhint %}

### Relation Options

Append relation options after the selected fields. Options use square brackets, are separated by commas, and are case-sensitive. A relation without field selection places the first option directly after `:`.

`?include={relation}:{field1},[{option}={value}]`

| Option       | Type      | Description                                                                                                             |
| ------------ | --------- | ----------------------------------------------------------------------------------------------------------------------- |
| `withCounts` | `string`  | Add counts for one or more related relations. Separate multiple relation names with `+`.                                |
| `order`      | `string`  | Order related records by one or more fields. Separate fields with `+` and prefix a field with `-` for descending order. |
| `limit`      | `integer` | Limit the number of related records.                                                                                    |
| `appends`    | `string`  | Add one or more computed fields to related records. Separate field names with `+`.                                      |
| `nestLevels` | `integer` | Repeat a self-referential relation for the specified number of additional nesting levels.                               |

**Combined example**

<mark style="color:green;">`GET`</mark> `/api/{route}?include=manualEntries:id,title,manual_chapter_id,[withCounts=seenUsers+readUsers],[order=-id],[limit=2],[appends=hash]`

**Self-referential example**

<mark style="color:green;">`GET`</mark> `/api/{route}?include=children:id,title,parent_id,[nestLevels=2]`

Relation options affect only supported, authorized relations. Invalid or unavailable relations are not made accessible by including them.

## Selects

Use `select` to restrict the response to specified public fields.

**Syntax**

* `{route}` - Endpoint from which records are retrieved.
* `?select` - Query parameter containing the fields.
* `{fields}` - Field keys separated by `,`.

<mark style="color:green;">`GET`</mark> `/api/{route}?select={fields}`

{% hint style="warning" %}
When combining `select` with `include`, include the field required to resolve each requested relation.
{% endhint %}

## Limiting

Use `limit` to control the maximum number of returned records.

**Syntax**

* `{route}` - Endpoint from which records are retrieved.
* `?limit` - Query parameter containing the maximum result count.
* `{value}` - Maximum number of records to return.

<mark style="color:green;">`GET`</mark> `/api/{route}?limit={value}`

For paginated endpoints with an exact count, `limit` also caps the reported total and can therefore reduce the last available page. Count-less endpoints still stop returning records after the limit is reached.

## Pagination

Pagination-enabled endpoints accept `page` and `per_page`. They default to page `1` with `25` records per page.

**Syntax**

* `{route}` - Pagination-enabled endpoint from which records are retrieved.
* `?page` - Query parameter containing the page number.
* `?per_page` - Query parameter containing the page size.

<mark style="color:green;">`GET`</mark> `/api/{route}?page=2&per_page=25`

Paginated responses contain `current_page`, `last_page`, `per_page`, `total`, `from`, `to`, and `data`. Endpoints that do not enable pagination ignore these shared pagination controls or document different behavior.

### Count-less Pagination

Some entity-selection and preview endpoints avoid an exact count. Their response keeps the standard pagination fields but returns `total` as `null`. While another page may exist, `last_page` is the next page number; otherwise it equals `current_page`. Clients can therefore test whether `last_page` is greater than `current_page` without treating it as an exact total page count.

## Sorting

Use `sort` to define the order of returned records.

**Syntax**

* `{route}` - Endpoint from which records are retrieved.
* `?sort` - Query parameter containing the sort fields.
* `{fields}` - Field keys separated by `,`; prefix a field with `-` for descending order.

<mark style="color:green;">`GET`</mark> `/api/{route}?sort={fields}`

For example, `?sort=-updated_at,title` sorts by `updated_at` descending and then by `title` ascending.

## Relation Counts

Use `with_count` to return the number of related records without returning those resource objects.

**Syntax**

* `{route}` - Endpoint from which records are retrieved.
* `?with_count` - Query parameter containing the relations.
* `{relations}` - Relation identifiers separated by `|`.

<mark style="color:green;">`GET`</mark> `/api/{route}?with_count={relations}`

Each count uses the snake-case relation name followed by `_count`. For example, `with_count=seenUsers|readUsers` adds `seen_users_count` and `read_users_count`.

## Appends

Use `appends` to add supported computed fields to API responses.

**Syntax**

* `{route}` - Endpoint from which records are retrieved.
* `?appends` - Query parameter containing the computed fields.
* `{fields}` - Computed field keys separated by `,`.

<mark style="color:green;">`GET`</mark> `/api/{route}?appends={fields}`

**Top-level example**

<mark style="color:green;">`GET`</mark> `/api/manual/entries/1?appends=hash`

Use the `appends` relation option for included relations. Top-level fields are separated by `,`, while relation-option fields are separated by `+`.

<mark style="color:green;">`GET`</mark> `/api/forms/1?include=formFields:[appends=field_validation_string]`

{% hint style="warning" %}
If an appended field depends on an attribute excluded by `select`, the appended output can be incomplete.
{% endhint %}

## Filters

The shared `filter` object accepts the field comparisons documented under [Value Filters](/introduction/query-manipulation/value-filters.md) and the relation conditions documented under [Constraints](/introduction/query-manipulation/constraints.md).

Resource-specific shortcut filters added on top of those shared operators are intentionally not part of the public API documentation yet.