Pagination

All API responses use a standard JSON envelope. List endpoints include pagination metadata to help you iterate through large datasets.

---

Response Envelope

Every response wraps its payload in a data field:

{
  "data": { ... }
}

List endpoints also include a pagination object:

{
  "data": [ ... ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 342,
    "has_next": true
  }
}

Pagination Fields

Field	Type	Description
page	integer	Current page number (1-indexed)
limit	integer	Number of items per page
total	integer	Total number of items across all pages
has_next	boolean	true if more pages are available

---

Query Parameters

All list endpoints accept these pagination parameters:

Parameter	Type	Default	Range	Description
page	integer	1	1+	Page number to retrieve
limit	integer	50	1-200	Number of items per page

---

Iterating Through Pages

Use has_next to determine when to stop paginating.

cURL

# Fetch page 1
curl "https://be.graph8.com/api/v1/contacts?page=1&limit=100" \
  -H "Authorization: Bearer $API_KEY"

# If has_next is true, fetch page 2
curl "https://be.graph8.com/api/v1/contacts?page=2&limit=100" \
  -H "Authorization: Bearer $API_KEY"

Python

import requests

API_KEY = "your_api_key_here"
BASE_URL = "https://be.graph8.com/api/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

all_contacts = []
page = 1

while True:
    response = requests.get(
        f"{BASE_URL}/contacts",
        headers=HEADERS,
        params={"page": page, "limit": 200}
    )
    data = response.json()

    all_contacts.extend(data["data"])

    if not data["pagination"]["has_next"]:
        break
    page += 1

print(f"Fetched {len(all_contacts)} contacts")

TypeScript

const API_KEY = "your_api_key_here";
const BASE_URL = "https://be.graph8.com/api/v1";

async function fetchAllContacts() {
  const allContacts = [];
  let page = 1;

  while (true) {
    const response = await fetch(
      `${BASE_URL}/contacts?page=${page}&limit=200`,
      { headers: { Authorization: `Bearer ${API_KEY}` } }
    );
    const { data, pagination } = await response.json();

    allContacts.push(...data);

    if (!pagination.has_next) break;
    page++;
  }

  return allContacts;
}

---

Best Practices

• Use the maximum limit (200) when exporting large datasets to minimize requests.
• Check has_next instead of computing from page * limit < total — this avoids off-by-one errors.
• Respect rate limits — add a short delay between pages if fetching many pages. See Rate Limits.
• Don’t assume order — results are returned in the default order for each resource. If you need a specific order, sort client-side.