Pagination
Page through list endpoints with the page and limit query parameters.
Last updated
The paginated list endpoints — contacts, clients, leads, escrows, listings, and appointments — take a limit query parameter and return the records under data, keyed by the resource name, with pagination metadata at data.meta. All of them except contacts choose the page with page:
curl "https://api.actuallycare.com/v1/clients?page=2&limit=50" \
-H "X-API-Key: YOUR_API_KEY"{
"success": true,
"data": {
"clients": [
{ "id": "7b1e9c44-2f6a-4d83-9c0e-5a1f2b3c4d5e" }
],
"meta": { "page": 2, "limit": 50, "total": 137, "totalPages": 3, "hasMore": true }
}
}The entity key matches the resource — data.clients here, data.leads on /v1/leads, data.listings on /v1/listings, data.appointments on /v1/appointments. (Records trimmed for brevity — each entry is a full object; the per-endpoint field lists are in the API reference.)
Parameters#
| Parameter | Type | Default | Notes |
|---|---|---|---|
page | integer | 1 | Which page to fetch, starting at 1. Ignored by /v1/contacts |
offset | integer | 0 | Records to skip. Use this on /v1/contacts: offset = (page - 1) * limit |
limit | integer | 25 | Records per page, maximum 100. /v1/escrows defaults to 20 and /v1/contacts to 50 |
Out-of-range values aren't clamped: a limit above 100 or below 1, or a page below 1, returns 400 VALIDATION_ERROR.
/v1/webhooks and /v1/api-keys aren't paginated — they return a plain array in data, with no meta.
Stick to the parameters documented for each endpoint in the API reference — don't invent sort or filter parameters that aren't listed there.
The meta object#
| Field | Meaning |
|---|---|
page | The page you got back |
limit | Records per page for this response |
total | Total matching records across all pages |
totalPages | Total number of pages at this limit |
hasMore | true while there are more pages to fetch |
You're done when hasMore is false — or, defensively, when a page comes back empty.
Fetch every page#
Both loops below request 100 records at a time (the maximum) and stop when data.meta.hasMore goes false.
JavaScript:
async function fetchAll(path, entity) {
const all = [];
let page = 1;
let hasMore = true;
while (hasMore) {
const res = await fetch(
`https://api.actuallycare.com/v1${path}?page=${page}&limit=100`,
{ headers: { "X-API-Key": process.env.ACTUALLYCARE_API_KEY } }
);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const body = await res.json();
all.push(...body.data[entity]);
hasMore = body.data.meta.hasMore;
page += 1;
}
return all;
}
const clients = await fetchAll("/clients", "clients");
// Not for /contacts — it ignores page. Page contacts with offset instead.Python:
import os
import requests
def fetch_all(path, entity):
records = []
page = 1
has_more = True
while has_more:
res = requests.get(
f"https://api.actuallycare.com/v1{path}",
headers={"X-API-Key": os.environ["ACTUALLYCARE_API_KEY"]},
params={"page": page, "limit": 100},
)
res.raise_for_status()
body = res.json()
records.extend(body["data"][entity])
has_more = body["data"]["meta"]["hasMore"]
page += 1
return records
clients = fetch_all("/clients", "clients")
# Not for /contacts — it ignores page. Page contacts with offset instead.Paginate less#
The fastest page is the one you don't fetch:
- Filter server-side where filters exist. For example,
GET /v1/listingsacceptsstatus,minPrice, andmaxPrice— filtering there beats downloading everything and filtering in your code. Each endpoint's filters are in the listings reference. - Mind the rate limit. Every page is one request against your rate limit, so a full export at
limit=100costs a request per hundred records. Cache results you'll reuse. - Don't poll for changes. If you're re-fetching everything on a schedule just to spot what changed, subscribe to webhooks instead and let ActuallyCare push the changes to you.