No Offset Pagination

Some of our API endpoints return long lists of data and use No Offset Pagination (or Cursor Pagination) to page through results. Instead of numeric offsets, each page contains a cursor that marks where to continue. This guide shows how it works using the "List OAIDs" endpoint as an example.

Example: Read List Of OAIDs

The "List OAIDs" endpoint limits how many records are returned per request, so multiple requests are needed to retrieve all records.

To control pagination, two query parameters are available:

• _page_cursor - a unique ID marking the starting point for the next page (defined in the next URL)
• _page_size - optional, the number of records to receive per page (default: 500, max: 2000)

Steps

1. Request the First Page

   In the first page request, simply use the base url (plus an optional _page_size query parameter if desired).

   $ curl --request GET "https://api.oaid.at/v2/pip/codes/?_page_size=500" \
   $  --header "Authorization: Bearer <access_token>" \
   $  --header "Accept: application/json"
   ---> 100%
   
   HTTP/1.1 200 OK
   date: Thu, 27 Mar 2025 19:25:35 GMT
   ...
   x-page-size: 500
   x-page-count: 163
   link: <https://api.oaid.at/v2/pip/codes/?_page_size=500>; rel=self, <https://api.oaid.at/v2/pip/codes/?_page_cursor=01953216-aaaa-788e-986e-822e157e5114&_page_size=500>; rel=next
   
   [
     {"oaid": "AB1C23E4", ...
     {"oaid": "AC4723E7", ...
     ...
   ]
   

2. Retrieve the next URL

   The next URL for pagination is provided in the API response header in the link field. The method for extracting the next URL varies depending on the programming language used. The Link header is common implementation for pagination.

   For instance, in the Python script below, we use the httpx package, which parses the links from the response header and stores them in the response.links object. If another page is available to retrieve, it will include a "next" object with the relevant "url" value for accessing the next page:

   next_url = response.links.get("next", {}).get("url")
   

3. Request Next Page

   Use the next_url obtained in Step 2 in your next request:

   request GET "https://api.oaid.at/v2/pip/codes/?_page_cursor=01953216-aaaa-788e-986e-822e157e5114&_page_size=500"                
   

4. Repeat Until Completion

   Repeat Steps 2 and 3 until no next URL is provided or the last page returns an empty page of data ([]), indicating all records have been retrieved.

Example Script (Python)

The following script automates pagination to fetch all pages of data. Please replace the <client_id> and <client_secret> placeholders with your credentials.

# /// Pagination Script
# requires-python = ">=3.11"
# dependencies = [
#     "httpx",
#     "httpx-auth"
# ]
# ///

import httpx
from httpx_auth import OAuth2ClientCredentials

BASE_URL = "https://api.oaid.at/v2/pip/codes/"

oauth2_cred = OAuth2ClientCredentials(
    token_url="<token_url>",            # use provided token_url
    client_id="<client_id>",            # fill in your client id
    client_secret="<client_secret>",    # fill in your client secret
    scope="read"                      
)

results_list = []
next_url = BASE_URL

with httpx.Client(headers={"Content-Type": "application/json"}, auth=oauth2_cred) as client:
    while next_url:
        response = client.get(url=next_url)
        results_list.extend(response.json())
        next_url = response.links.get("next", {}).get("url")

print(f"Total records: {len(results_list)}")