Pagination
To request a subset of a collection of resources, pagination can be used. You can use either offset-based pagination or date-based pagination.
Offset-based
Offset-based pagination uses the offset and limit parameters. These work on all collections, but the downside is when new resources are added to the collection between the fetching of pages by the client, you may get overlap in responses. If resources are removed between page fetches, resources may be skipped by the pagination.
Date-based
Date-based pagination uses at least one of the date_after, date_before, date_since or date_until parameters and can be used to avoid the problems described with offset-based pagination.
CUSTOM-NOTE
date_after and date_before are exclusive, whereas date_since and date_until are inclusive.
It is possible to specify a date for both the beginning of the page and the end of the page, but it is also possible to specify a single date property and combine it with the limit parameter.
Query Parameters
| Name | Type | Description |
|---|---|---|
| date_after[path] | datetime | ISO 8601 compliant timestamp (including timezone) |
| date_before[path] | datetime | ISO 8601 compliant timestamp (including timezone) |
| date_since[path] | datetime | ISO 8601 compliant timestamp (including timezone) |
| date_until[path] | datetime | ISO 8601 compliant timestamp (including timezone) |
| limit[path] | integer | Maximum number of records to return |
| offset[path] | integer | Number of records to skip |
Adding a path to any of the parameters is optional. Without a path, limit applies to the main resource and any embedded collections. Since API v2024.3.0, a path-less offset applies only to the main resource — embedded collections default to offset 0 unless given an explicit offset[path]. When a non-self path is specified, it applies only to the collection referenced by the path.
To paginate a collection that is itself the main resource (a root/list endpoint), key on self — e.g. limit[self]=50&offset[self]=0 — or use the path-less form, which targets the same collection (limit=50&offset=0). Using the resource/embed name instead (e.g. limit[categories]) is wrong and silently falls back to the default limit. limit[self] and the path-less limit are the same key and behave identically in every respect — the root/self limit is also the default inherited by every embedded collection unless overridden by a limit[<path>].
To paginate a collection pulled in via embed=, key on the embed name, including nested paths — e.g. limit[messages.replies]=3 or offset[messages.recipients]=0.
The /search endpoint has no collection of its own as the main resource; paginate each result type by its embed key instead — e.g. limit[messages:news]=2. self and the path-less form have no effect there.
If you do not send a limit, the collection defaults to returning 10 records.
Prefer the array form (limit[self], limit[messages.replies]); the path-less, string-only forms (limit=50, offset=0) are discouraged. Never combine a path-less and a bracketed form of the same parameter in one request: a path-less limit (equivalently limit[self]) is also inherited by embedded collections, so pairing it with a limit[...] can silently cap embeds you did not intend to touch.
Pagination support by message type
| Message type | Date | Offset | Comment |
|---|---|---|---|
| Private conversation[/networks/EID/messages/?conversation=EID] | ✓ | ✗ | |
| Comment[/networks/EID/messages/?parent=EID] | ✗ | ✓ | |
| Announcement[/networks/EID/announcement] | ✗ | ✓ | |
| File[/networks/EID/recentfiles OR /networks/EID/messages/?parent_folder=EID] | ✗ | ✓ | |
| Task[/networks/EID/tasks/] | ✗ | ✓ | |
| Event[networks/EID/events/] | ✓ | ✓ | Date filter keys are start_from(datetime) and start_before(datetime) |
| Event(past)[/networks/EID/events/past/] | ✓ | ✓ | Date filter keys are start_before_or_at(datetime) and last_seen_eid(EID) |
| Poll[/networks/EID/messages/?type=poll] | ✓ | ✗ | |
| News[/networks/EID/news/] | ✓ | ✗ |
Syntax
property path = [ resource ], { ".", ? resource name ? } ".", ? property name ? ;
resource = "self" | ? resource name ? ;