# Pagination, sorting, and meta information

Some of the Investment API endpoints return lists of resources instead of single items. Those lists of resources can be quite large, so we provide pagination and sorting of those resources to allow you to manage the responses more efficiently.

Additionally the response payloads from these endpoints conform to a standard top-level data structure, described in the section [Meta information](#data-and-meta-information), below.

## Pagination

Endpoints that expose lists of resources may be paginated. This means that if there are many resources, they can be retrieved in segments divided into pages rather than in a single result. Please refer to the [API Reference](/api) documentation to see if an individual endpoint support this.

When using a paginated endpoint you may provide the following query parameters:

| Query parameter | Purpose |
|  --- | --- |
| `limit` | Number of items per response. Maximum allowed is `10000`. Default is `100` |
| `offset` | The page offset you wish to return. Each page contains a maximum `limit` items. |


The order of resources in your pages follows the [Sorting](#Sorting) rules, described below.

**Default pagination**

If you do not specify either of these parameters, you will get a list with a maximum of 1000 entries and an offset of 0 (i.e. the beginning of the list).

## Sorting

Some endpoints allow you to define the sorting order of the returned list. Individual endpoints specify which fields you can sort by. Please refer to the [API Reference](/api) documentation for the endpoint in question to see more details.

When an endpoint supports sorting, you may pass the following query parameters to sort the resources in the response.

| Query parameter | Purpose |
|  --- | --- |
| `sort` | Field name of the single resource by which a list is to be sorted. |
| `order` | Sorting order. Either `ASC` or `DESC` for ascending or descending sorting order respectively. Default is `ASC`. |


**No default sort order**

There is no global default sort order for resources returned from sortable endpoints. Check the [API Reference](/api) for details of the endpoint you're using.

## Data and Meta information

Each endpoint that allows pagination contains a response with the fields `data` and `meta`.

The `data` field is a list that contains all the individual resource information defined in the endpoint descriptions section. Its length will not exceed the `limit` you have set by query parameter, or 1000 items if you omitted that parameter. Its ordering will be undefined unless you have passed explicit `sort` and `order` parameters.

The `meta` field contains relevant meta information about the returned list. It will provide you with the following information:

| Field name | Description |
|  --- | --- |
| `offset` | Quantity of resource to be offset in the response. |
| `limit` | Total limit of the response. |
| `count` | Number of resources returned in the response. |
| `total_count` | Total number of all resources. |
| `sort` | Field by which a list is sorted. |
| `order` | Sorting order of the response (`ASC` or `DESC`). |


## Examples

Imagine a request to an endpoint that return 105 items (for this example we'll use the [`/instruments`](/api/instruments/list_instruments) endpoint).

### Limit query parameter

If you specify the `limit` query parameter as `10` you will only receive 10 resources in each response.

We've omitted the `offset` parameter, which is equivalent to setting it explicitly to `0`. Thus, you will receive the first 10 resources.

Example request
**GET** `/instruments?limit=10`

Example response

```json
{
"meta": {
  "offset": 0,
  "limit": 10,
  "count": 10,
  "total_count": 105,
  "sort": "ASC",
  "order": "created_at"
},
"data": [
    {
        "id": "001" // Note, in reality this is a UUID
        // Instrument details omitted for brevity
        "created_at": "2022-08-31T17:28:00.00Z",
        "updated_at": "2022-08-31T17:28:00.00Z",
    },
    {
        "id": "002",
        "created_at": "2022-09-01T18:50:00.00Z",
        "updated_at": "2024-01-91T10:28:00.00Z",
    },
    // ... 7 more items omitted for brevity
    {
        "id": "010",
        "created_at": "2022-10-12T14:22:00.00Z",
        "updated_at": "2022-11-01T11:45:00.00Z",
    }
]
}
```

### Sort & order

The `sort` and `order` fields are in the response's `meta` object, even though we didn't explicitly set them. These are the defaults for the [`/instruments`](/api/instruments/list_instruments) endpoint.

A glance at the documentation tells us that we can also order by the `updated_at` field, and of course we could choose to sort descending order too. That request would look like this:

Example request
**GET** `/instruments?limit=10&sort=updated_at&order=DESC`

Example response

```json
{
"meta": {
 "offset": 0,
 "limit": 10,
 "count": 10,
 "total_count": 105,
 "sort": "DESC",
 "order": "updated_at"
},
"data": [
   {
       "id": "105" // Note, in reality this is a UUID
       // details omitted for brevity
       "created_at": "2024-04-01T17:28:00.00Z",
       "updated_at": "2024-04-26T12:12:00.00Z",
   },
   {
       "id": "002",
       "created_at": "2022-09-01T18:50:00.00Z",
       "updated_at": "2024-01-91T10:28:00.00Z",
   },
   // ... 7 more items 
   {
       "id": "104",
       "created_at": "2022-02-10T14:22:00.00Z",
       "updated_at": "2023-11-01T11:45:00.00Z",
   }
]
}
```

We would then see a potentially different set of resources populating our first page of responses, and our parameters would be reflected back to us in the `meta` object of the response.  That response might look like this:

Note that items 1-10 returned at `offset` 0, are now the ten most recently updated instruments.

### Offset

If you then repeat the request, but increase the `offset` to `1`, you will then receive items 11 to 20.

Increasing the `offset` to `2` will return resources 21 to 30.  Finally at an `offset` of `10` you'll receive only items 101 to 105, as there are no further resources to return.

That request would look like this:

Example request
**GET** `/instruments?limit=10&offset=1&sort=updated_at&order=DESC`

Example response

```json
{
  "meta": {
    "offset": 10,
    "limit": 10,
    "count": 5,
    "total_count": 105,
    "sort": "DESC",
    "order": "updated_at"
  },
//... remainder omitted for brevity
}
```

Note that in the final response at `offset` 10, the meta data will reflect that there are less than ten items in the page.