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, 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 documentation to see if an individual endpoint support this.

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

The order of resources in your pages follows the Sorting rules, described below.

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 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.

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.

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:

Example

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. That request might look like this:

GET /instruments?limit=10

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

The response would look something like this:

{
  "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",
      }
  ]
}

Note that 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:

{
  "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",
      }
  ]
}

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. That request would look like this:

GET /instruments?limit=10&offset=1&sort=updated_at&order=DESC

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.

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

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