Pagination

The Sphere API uses pagination on all endpoints that return lists of objects. Two pagination strategies are available: offset-based for standard collections and cursor-based for large, append-only datasets like the timeline and inbox.

GET/core/api/v1/families?page=1&per_page=50

Offset-based pagination

Offset-based pagination is the default strategy used by most list endpoints. You control the page number and the number of items per page.

Name
page
Type
integer
Description
The page number to retrieve. Defaults to 1.
Name
per_page
Type
integer
Description
The number of items per page. Defaults to 50. Maximum is 100.

The response includes a meta object with pagination metadata that tells you the current page, total pages, and total item count.

GET

/core/api/v1/families?page=2&per_page=25

curl -G https://your-sphere.example.com/core/api/v1/families \
  -H "Authorization: Bearer {token}" \
  -d page=2 \
  -d per_page=25

Offset-based response

{
  "data": [
    {
      "id": "f1a2b3c4-...",
      "code": "contact",
      "label": "Contact"
    },
    {
      "id": "e5f6a7b8-...",
      "code": "company",
      "label": "Company"
    }
  ],
  "meta": {
    "current_page": 2,
    "last_page": 4,
    "per_page": 25,
    "total": 98
  }
}

GET/core/api/v1/timeline?cursor=...&limit=50

Cursor-based pagination

Cursor-based pagination is used for large, frequently updated datasets where offset pagination would be inefficient or produce inconsistent results. The timeline and inbox endpoints use this strategy.

Instead of page numbers, you pass an opaque cursor string that points to a position in the result set. The API returns a next_cursor you can use to fetch the next batch.

Name
cursor
Type
string
Description
An opaque cursor string from a previous response. Omit this parameter to start from the beginning.
Name
limit
Type
integer
Description
The number of items to return. Defaults to 50. Maximum is 100.

Cursor values are opaque strings. Do not attempt to parse, modify, or construct them. Always use the next_cursor value returned by the API.

GET

/core/api/v1/timeline?limit=50

curl -G https://your-sphere.example.com/core/api/v1/timeline \
  -H "Authorization: Bearer {token}" \
  -d limit=50

Cursor-based response

{
  "data": [
    {
      "id": "evt-a1b2c3d4-...",
      "type": "entity.created",
      "occurred_at": "2026-02-24T10:30:00Z"
    },
    {
      "id": "evt-e5f6a7b8-...",
      "type": "entity.updated",
      "occurred_at": "2026-02-24T10:28:00Z"
    }
  ],
  "meta": {
    "next_cursor": "eyJpZCI6MTAwLCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9",
    "has_more": true
  }
}

GET/core/api/v1/entities?sort=created_at&direction=desc

Sorting

Most list endpoints support sorting via query parameters. You can specify the field to sort by and the direction.

Name
sort
Type
string
Description
The field to sort by. Common values: created_at, updated_at, name, label. Available fields depend on the endpoint.
Name
direction
Type
string
Description
The sort direction: asc (ascending) or desc (descending). Defaults to desc for timestamp fields, asc for name fields.

Sorting works with both offset-based and cursor-based pagination.

GET

/core/api/v1/entities?sort=created_at&direction=desc

curl -G https://your-sphere.example.com/core/api/v1/entities \
  -H "Authorization: Bearer {token}" \
  -d sort=created_at \
  -d direction=desc \
  -d per_page=25

Choosing a pagination strategy

Strategy	Best for	Endpoints
Offset-based	Browsable collections with stable order (families, entities, users)	Most list endpoints
Cursor-based	Large, append-heavy datasets where consistency matters	Timeline, Inbox

If you are building a UI with "Load more" or infinite scroll, cursor-based pagination provides the best experience — it avoids duplicate or missing items when new data is inserted between page fetches.