Pagination

Overview

The Health Plans API uses cursor-based (keyset) pagination for consistent, performant page traversal. This approach is more reliable than offset-based pagination when data changes between requests.

How It Works

1. Make an initial search request
2. Check _links.next in the response for the next page URL
3. Follow the next link to get the next page
4. Repeat until _links.next is absent (last page)

Example: Paginating Through Results

Python

import requests

url = "https://api.opelyx.com/v1/health/plans"
headers = {"Authorization": "Bearer op_YOUR_API_KEY_HERE"}
params = {"zip": "10001", "age": 30, "page_size": 10}

all_plans = []
while url:
    response = requests.get(url, headers=headers, params=params)
    data = response.json()
    all_plans.extend(data["_embedded"]["plans"])

    # Follow the next link if available
    next_link = data.get("_links", {}).get("next", {}).get("href")
    url = next_link
    params = None  # params are encoded in the cursor URL
print(f"Fetched {len(all_plans)} plans total")

JavaScript

const headers = { Authorization: "Bearer op_YOUR_API_KEY_HERE" };
let url = "https://api.opelyx.com/v1/health/plans?zip=10001&age=30&page_size=10";
const allPlans = [];

while (url) {
  const response = await fetch(url, { headers });
  const data = await response.json();
  allPlans.push(...data._embedded.plans);

  url = data._links?.next?.href ?? null;
}
console.log(`Fetched ${allPlans.length} plans total`);

curl

# Page 1
curl -H "Authorization: Bearer op_YOUR_API_KEY_HERE" \
  "https://api.opelyx.com/v1/health/plans?zip=10001&age=30&page_size=10"

# Page 2 (use the cursor from _links.next.href)
curl -H "Authorization: Bearer op_YOUR_API_KEY_HERE" \
  "https://api.opelyx.com/v1/health/plans?zip=10001&age=30&page_size=10&cursor=eyJpZCI6MTB9"

Response Structure

{
  "_links": {
    "self": { "href": "https://api.opelyx.com/v1/health/plans?zip=10001&age=30" },
    "next": { "href": "https://api.opelyx.com/v1/health/plans?zip=10001&age=30&cursor=eyJpZCI6MjB9" }
  },
  "_embedded": {
    "plans": [ "..." ]
  },
  "total": 145,
  "page_size": 20
}

Tip

The total field gives you the full count of matching plans, so you can show “Page X of Y” in your UI even with cursor pagination.

Page Size

Control the number of results per page with the page_size parameter:

• Minimum: 1
• Maximum: 100
• Default: 20