# 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:
*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:
```shellscript
Link: ; 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:
```shellscript
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:
```shellscript
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:
```python
import requests
BASE_URL = "https://api.genlogs.io"
headers = {
"Access-Token": "",
"x-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
```python
const headers = {
"Access-Token": "",
"x-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.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.genlogs.io/getting-started/pagination.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.