Pagination

When dealing with large sets of data, receiving results in segments can help apps process information in a more structured way. This retrieval of data, a page at a time, is called pagination.

The /transactions endpoint will standardize on link-based pagination with Akoya API v2.

Consider the following when implementing link-based pagination.

1️⃣ First request

When making an initial transaction call, create the request with the following parameters. The result of that first request will return links to use for paging.

Parameters

These parameters should only be used in constructing the first transaction call. After the first call, requesting pages must be done with links provided in results.

Some data providers may not support offset or limit. Please check the Data Recipient Hub for specific provider documentation for details on pagination support.

  • offset - The number of items to skip before the first in the response
  • limit - The maximum number of items to be returned in the response
  • startTime - ISO 8601 date format in UTC time zone. Example: 2020-03-30T04:00:00Z
  • endTime - ISO 8601 date format in UTC time zone. Example: 2021-03-30T04:00:00Z

📘

Use of the offset parameter

When using Akoya’s link-based pagination, we recommend omitting the offset parameter in the initial transaction call.

Request

Example

The following example uses our sandbox and the following parameter values in the original transactions request:

  • providerId = Mikomo
  • accountId = g833202fb0866d0ad83472c429
  • limit = 5
  • startTime = 2019-02-26T00:00:00Z
  • endTime = 2021-02-26T00:00:00Z
curl --location --request GET 'https://sandbox-products.ddp.akoya.com/transactions/v2/mikomo/g833202fb0866d0ad83472c429?startTime=2019-02-26T00:00:00Z&endTime=2021-02-26T00:00:00Z&limit=5' --header 'Content-Type: application/json' --header 'Authorization: Bearer {{idToken}}

Response

Example response with paging

The value of links.next.href may contain the offset, limit, start time, and end time parameters. You should not change these values and use the link as provided.

{
    "links": {
        "next": {
            "href": "/transactions/v2/mikomo/g833202fb0866d0ad83472c429?endTime=2021-02-26T00%3A00%3A00Z&limit=5&offset=5&startTime=2019-02-26T00%3A00%3A00Z"
        },
        "prev": {
            "href": "/transactions/v2/mikomo/g833202fb0866d0ad83472c429?endTime=2021-02-26T00%3A00%3A00Z&limit=5&offset=0&startTime=2019-02-26T00%3A00%3A00Z"
        }
    },
    "transactions": [
        {
            "depositTransaction": {
                "accountId": "g833202fb0866d0ad83472c429",
                "amount": -449.07,
                "checkNumber": 31505,
                "description": "CHECK",
                "postedTimestamp": "2019-07-08T00:00:00Z",
                "status": "POSTED",
                "transactionId": "30191890000030",
                "transactionTimestamp": "2019-07-08T00:00:00Z",
                "transactionType": "CHECK"
            }
        },
        {
            "depositTransaction": {
                "accountId": "g833202fb0866d0ad83472c429",
                "amount": -4000.4,
                "checkNumber": 31528,
                "description": "CHECK",
                "postedTimestamp": "2019-07-08T00:00:00Z",
                "status": "POSTED",
                "transactionId": "30191890000020",
                "transactionTimestamp": "2019-07-08T00:00:00Z",
                "transactionType": "CHECK"
            }
        },
        {
            "depositTransaction": {
                "accountId": "g833202fb0866d0ad83472c429",
                "amount": 5048.13,
                "description": "DEPOSIT",
                "postedTimestamp": "2019-07-08T00:00:00Z",
                "status": "POSTED",
                "transactionId": "30191890000010",
                "transactionTimestamp": "2019-07-08T00:00:00Z",
                "transactionType": "DEPOSIT"
            }
        },
        {
            "depositTransaction": {
                "accountId": "g833202fb0866d0ad83472c429",
                "amount": -8.6,
                "checkNumber": 31530,
                "description": "CHECK",
                "postedTimestamp": "2019-07-09T00:00:00Z",
                "status": "POSTED",
                "transactionId": "30191900000030",
                "transactionTimestamp": "2019-07-09T00:00:00Z",
                "transactionType": "CHECK"
            }
        },
        {
            "depositTransaction": {
                "accountId": "g833202fb0866d0ad83472c429",
                "amount": -42.94,
                "checkNumber": 31525,
                "description": "CHECK##TRANINITDATE# 07/09",
                "postedTimestamp": "2019-07-09T00:00:00Z",
                "status": "POSTED",
                "transactionId": "30191900000020",
                "transactionTimestamp": "2019-07-09T00:00:00Z",
                "transactionType": "CHECK"
            }
        }
    ]
}

Example without pagination

If all data can be returned without paging, the links.next.href values will be empty. There is no additional data to page through.
Example with sandbox user mikomo_10, accountId = "5426873"

{
    "links": {
        "prev": {
            "href": "/transactions/v2/mikomo/5426873?endTime=2021-05-19T00%3A00%3A00Z&limit=50&offset=0&startTime=2021-05-16T00%3A00%3A00Z"
        }
    },
    "transactions": [
        {
            "investmentTransaction": {
                "accountId": "5426873",
                "amount": -30000,
                "commission": 0,
                "debitCreditMemo": "DEBIT",
                "description": "CHASE DEPOSIT SWEEP JPMORGAN CHASE BANK NA INTRA-DAY DEPOSIT",
                "fees": 0,
                "fractionalCash": 0,
                "memo": "CHASE DEPOSIT SWEEP JPMORGAN CHASE BANK NA INTRA-DAY DEPOSIT",
                "positionType": "LONG",
                "postedTimestamp": "2021-05-17T00:00:00Z",
                "securityId": "QACDS",
                "securityIdType": "SYMBOL",
                "status": "POSTED",
                "subAccountFund": "CASH",
                "subAccountSec": "CASH",
                "symbol": "QACDS",
                "transactionId": "TX-300000020210517#20210517--1321227038",
                "transactionTimestamp": "2021-05-17T00:00:00Z",
                "transactionType": "PURCHASED",
                "transferAction": "OUT",
                "unitPrice": 0,
                "units": 30000
            }
        }
    ]
}

2️⃣ Second request

Use the links.next.href value in the first response payload to construct the next call.

Do not change the link. Changes to offset, startTime, endTime, or limit in the provided link may cause errors or missing data.

For example, in the first response, links.next.href was returned as:

"links": {
        "next": {
            "href": "/transactions/v2/mikomo/g833202fb0866d0ad83472c429?endTime=2021-02-26T00%3A00%3A00Z&limit=5&offset=5&startTime=2019-02-26T00%3A00%3A00Z"
        },
        "prev": {
            "href": "/transactions/v2/mikomo/g833202fb0866d0ad83472c429?endTime=2021-02-26T00%3A00%3A00Z&limit=5&offset=0&startTime=2019-02-26T00%3A00%3A00Z"
        }
    }

Next page request

To request the next page, use the links.next.href value in the GET request:

curl --location --request GET 'https://{access_url}{{links.next.href}} \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Bearer {{idToken}}'

Previous page request

Most pagination responses will include links.prev.href. It may be used to page back to previous results. However, a small number of providers do not support prev. Check the Data Recipient Hub for specific provider documentation for details on pagination support. If prev is not supported and your app requires it, store the next links as the user pages.

3️⃣ Ongoing requests

Continue to make requests using the provided links until next is no longer returned in the response.