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

# Pagination, sorting, and filtering

> Learn how to optimize data you receive with GET API calls from Tesouro.

You can control what and how data is returned from the Tesouro API by using the following techniques:

## Pagination

Pagination is a process of dividing the resulting set of data into discrete blocks of information (pages). It decreases both the server payload and the network traffic and increases the speed of page loading.

For example, in Tesouro you may have 1000 payables registered and want to receive them in groups of 1-100, where 100 is the maximum of documents that can be requested at a time.

### Page size (limit)

To avoid server and network overloading, the number of returned records in `GET` requests is restricted. In API requests the `limit` query parameter defines the number of records that the API consumer wants to receive in the response. Possible values are 1 to 100. Values outside of this range will result in the HTTP error 416 (Requested range not satisfiable).

## Sorting

When querying collections (for example,`GET /payables` or `GET /counterparts`), you can sort the results by using the `sort` and `order` query parameters.

The `sort` parameter specifies the data field by which the results should be sorted. The available sort fields vary depending on the endpoint. The default sort field is `created_at`. Endpoints without the `sort` parameter also return the results sorted by `created_at`.

The `order` can be `asc` (ascending) or `desc` (descending). Default is `asc`.

<Info>
  If the response is paginated, all pages use the same sorting and filters as specified in the
  initial request. Sorting and filters cannot be modified for subsequent pages.
</Info>

## Filtering

Very often API consumers may want to retrieve only selected records rather than all available sets of records. For example, a user is interested only in payables created 10 days ago or later. To achieve this, you can provide filters in the request query string.

Filters can be of two types:

* Exact match (case-sensitive):

  ```lines theme={null}
  FIELD=VALUE
  ```

  For example, `name=Acme` or `price=1000`.

* Comparison filters:

  ```lines theme={null}
  FIELD__OPERATOR=VALUE
  ```

  For example, `created_at__gte=2022-01-01T00%3A00%3A00` returns items created on or after January 1, 2022. See the list of operators below.

Multiple filters can be combined using `&` (logical AND).

<Info>
  The supported filter fields and operators vary per endpoint. Refer to the endpoint reference for
  the exact supported filters.
</Info>

### Filter operators

| Operator    | Applicable field types | Description                                                                                                                                                                                                                           | Example                              |
| ----------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| `iexact`    | string                 | Case-insensitive equals.                                                                                                                                                                                                              | `name__iexact=acme`                  |
| `contains`  | string                 | Contains the specified string (case sensitive).                                                                                                                                                                                       | `name__contains=Acme`                |
| `icontains` | string                 | Contains the specified string (case insensitive).                                                                                                                                                                                     | `name__icontains=acme`               |
| `in`        | string                 | Represents the value in \[a, b, c] condition, that checks if the field value equals one of the specified values (case-sensitive). Each value requires a separate in filter, for example:<br />`field__in=value1&field__in=value2&...` | `status__in=draft&status__in=issued` |
| `gte`       | number, date-time      | Greater than or equal to the specified value.                                                                                                                                                                                         | `price__gte=5000`                    |
| `gt`        | number, date-time      | Greater than the specified value.                                                                                                                                                                                                     | `price__gt=5000`                     |
| `lte`       | number, date-time      | Less than or equal to the specified value.                                                                                                                                                                                            | `price__lte=5000`                    |
| `lt`        | number, date-time      | Less than the specified value.                                                                                                                                                                                                        | `price__lt=5000`                     |
| `isnull`    | any                    | `isnull=true` finds items where the specified field value is `null`.<p>`isnull=false` finds items where the specified field value is *not* `null`.</p>                                                                                | `entity_user_id__isnull=false`       |

### Query examples

* No filters. Only the sorting and limit fields are specified:

  ```lines theme={null}
  GET /products?limit=10&sort=name&order=desc
  ```

* Filtering by date and limiting the result set:

  ```lines theme={null}
  GET /products?limit=2&created_at__gte=2021-10-05T00:00:00
  ```

* Filtering by two fields with the default pagination:
  ```lines theme={null}
  GET /products?currency=USD&price__lte=10
  ```

### Response example

If the data is selected based on the specified conditions, the response will look like this:

```json lines theme={null}
{
    "data": [
      // array of records
      { ... },
      { ... },
      ...
    ],
    "prev_pagination_token": "bGltaXQ9MiZmaXJzdF9vaWQ9MSZwcmV2X3Rva2VuPTM=",
    "next_pagination_token": "bGltaXQ9MiZmaXJzdF9vaWQ9MSZuZXh0X3Rva2VuPTQ="
}
```

The `next_pagination_token` and `prev_pagination_token` values can passed in the `pagination_token` query parameter to receive the next or previous page in the result set.

## Error codes

When something goes wrong with pagination or filtering, one of the following HTTP response codes is returned:

* 406 Not Acceptable
* 416 Range Not Satisfiable