Pagination | Genlogs API Docs

Overview

Some Genlogs API endpoints return large result sets that are split across multiple pages. When this happens, the API returns a subset of results along with pagination headers that allow you to retrieve the remaining pages.

Pagination is currently available on the following endpoints:

Endpoint Paginated when Page Size
GET /facilities include_lanes=true 20

This page will be updated as pagination support is added to additional endpoints.

Navigating pages with the Link header

Paginated responses include a Link header containing URLs for navigating between pages. If all results fit on a single page, the Link header is omitted.

A typical Link header looks like this:

Link: <https://api.genlogs.io/facilities?zip_code=91761&include_lanes=true&cursor=eyJ0b3...>; rel="next"

The following relationships may appear:

Relationships Meaning
rel="next" URL for the next page of results
rel="prev" URL for the previous page of results

rel="next" is absent on the final page. rel="prev" is absent on the first page.

To retrieve the next page, make a request to the URL provided in the Link header. The URL includes all original query parameters along with a cursor value; there is no need to rebuild the request.

Tracking total results with X-Total-Count

Every paginated response includes an X-Total-Count header with the total number of matching results across all pages. This can be used for progress indicators or to determine how many pages to expect.

X-Total-Count: 999

This value is consistent across all pages of a result set.

Inspecting pagination headers

To verify pagination is working, you can inspect response headers using curl:

curl --include \
--url "https://api.genlogs.io/facilities?zip_code=91761&include_lanes=true" \
--header "Access-Token: [your-token]" \
--header "x-api-key: [your-api-key]" \

The --include flag prints the response headers above the body, allowing you to see the Link and X-Total-Count values.

You can use the URLs from the Link header to request another page of results. For example, to request the next page based on the previous example:

curl --include --request GET \
--url "https://api.genlogs.io/facilities?zip_code=91761&include_lanes=true&cursor=eyJ0b3..." \
--header "Access-Token: [your-token]" \
--header "x-api-key: [your-api-key]" \

The URLs in the Link header include the cursor query parameter, which the server uses to determine which page to return. The cursor value is opaque; do not attempt to parse, modify, or construct it. Always use the complete URL provided in the Link header.

Iterating through pages programmatically

Python

The requests library parses the Link header automatically via response.links. The following script collects all facilities across every page:

import requests

BASE_URL = "https://api.genlogs.io"
headers = {
    "Access-Token": "<your-token>",
    "x-api-key": "<your-api-key>",
}

url = f"{BASE_URL}/facilities?zip_code=91761&include_lanes=true"
facilities = []

while url:
    response = requests.get(url, headers=headers)
    response.raise_for_status()
    facilities.extend(response.json())
    url = response.links.get("next", {}).get("url")

total = response.headers.get("X-Total-Count")
print(f"Fetched {len(facilities)} of {total} facilities")

Javascript

const headers = {
    "Access-Token": "<your-token>",
    "x-api-key": "<your-api-key>",
};

let url = "https://api.genlogs.io/facilities?zip_code=91761&include_lanes=true";
const facilities = [];
let lastResponse;

while (url) {
    lastResponse = await fetch(url, { headers });
    const data = await lastResponse.json();
    facilities.push(...data);

const linkHeader = lastResponse.headers.get("Link") || "";
    const match = linkHeader.match(/<([^>]+)>;\s*rel="next"/);
    url = match ? match[1] : null;
}

const total = lastResponse.headers.get("X-Total-Count");
console.log(`Fetched ${facilities.length} of ${total} facilities`);

Things to know: