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, below.
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 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 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).
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 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 for details of the endpoint you're using.
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). |
Imagine a request to an endpoint that return 105 items (for this example we'll use the /instruments endpoint).
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.
GET /instruments?limit=10
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 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:
GET /instruments?limit=10&sort=updated_at&order=DESC
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.
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:
GET /instruments?limit=10&offset=1&sort=updated_at&order=DESC
Note that in the final response at offset 10, the meta data will reflect that there are less than ten items in the page.