Pagination

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_lan
  es=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:

• Cursor values are opaque. Do not parse, modify, cache long-term, or construct cursor values. Always follow the URL provided in the Link header.

• Authentication is required on every page request. Include your Access-Token and x-api-key headers on each request, including subsequent pages.

• Cursors do not expire. You can pause between page requests without losing your position in the result set.

• All query filters are preserved. The server embeds your original query parameters (zip_code, include_lanes, etc.) in the Link URL. You do not need to re-supply them.

• Backwards compatible. Requests that do not include a cursor parameter behave exactly as before. Existing integrations require no changes.

• Not supported with smart search. Combining the cursor parameter with smart_search=true returns a 400 Bad Request error.