Pagination and sorting

Every list route returns a paginated result. The same four parameters apply everywhere, which means one traversal helper covers the whole API.

Parameter	Type	Default	Role
page	integer	1	Page number, starting at 1
page_size	integer	10	Number of items per page
sort_by	string	created_at	Field to sort on
sort_order	asc | desc	desc	Sort direction

curl "https://api.metaventus.com/v1/entities?entity_type=contact&page=2&page_size=50&sort_by=created_at&sort_order=asc" \
  -H "X-API-Key: YOUR_API_KEY"

Shape of the response

Items sit in data, pagination state in meta:

{
  "data": [ { "id": "…" } ],
  "meta": {
    "page": 2,
    "page_size": 50,
    "total": 1284,
    "sort_by": "created_at",
    "sort_order": "asc"
  }
}

total counts the items matching the filter, not the ones on the page. The number of pages follows: ceil(total / page_size).

Walking a whole list

Increase page until you receive fewer items than page_size, or until you pass total. A large page costs a single request where unit calls cost as many as there are items — which is what makes the difference against the rate limits.

Sorting and concurrent inserts

Sorting created_at descending shifts items from one page to the next if records are created while you walk the list. For a reliable export, sort asc on created_at: new records then arrive at the end of the walk instead of pushing everything else along.