To fetch every event or delivery, follow the next-page link until it is null. Paginated operations return one page at a time. The link is a query string, relative to the URL of the request that returned it.
Paginated operations
| Operation | Filters | Order |
|---|---|---|
| List events | status, destinationId | Newest first |
| List deliveries | status, eventId, destinationId | Newest first |
List destinations and List sources return every destination or source in one page, newest first, so their links.next is always null.
Response shape
{
"data": [
{ "id": "evt_01m4pa5v4wetwab7xhgrev2tag", "type": "customer.created", "status": "unmatched" },
{ "id": "evt_01m4pa5v4bebst7x9c0fm1g1x2", "type": "customer.created", "status": "unmatched" }
],
"links": {
"next": "?limit=2&status=unmatched&cursor=evt_01m4pa5v4bebst7x9c0fm1g1x2"
}
}The items in data are shortened here. Each operation's reference page has the full item shape.
| Field | Type | Description |
|---|---|---|
data | array | The items in this page |
links.next | string or null | A query string that requests the next page. null on the last page. |
Query parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
limit | number | 100 | Items per page, from 1 to 100 |
cursor | ID | None | Return items that sort before this ID. Taken from links.next. |
A limit outside 1 to 100, or a cursor that isn't an ID of the listed resource, fails with 400 validation_failed.
The next link
links.next starts with ?. It is a URI reference relative to the URL of the request that returned the page, as defined by RFC 3986. Resolved against that URL, it keeps the scheme, host and path and replaces the whole query string.
The link carries the limit and every filter of the original request, plus cursor. The next page therefore uses the same filters and page size.
| Request | links.next | Next request |
|---|---|---|
/v1/events?status=unmatched&limit=2 | ?limit=2&status=unmatched&cursor=evt_01m4pa5v4bebst7x9c0fm1g1x2 | /v1/events?limit=2&status=unmatched&cursor=evt_01m4pa5v4bebst7x9c0fm1g1x2 |
links.next is null when no item sorts after the last item of the page. Stop when it is null, not when a page is short.
A page can hold fewer than limit items, or none, and still have a links.next. This is most likely with a filter that matches few items. Keep following the link.
Example
This script lists every event in the app. new URL(next, url) resolves the link against the URL of the previous request.
const headers = { authorization: `Bearer ${process.env.PAYLOADPUFFIN_API_KEY}` };
let url = new URL(`https://api.payloadpuffin.com/v1/events?limit=50`);
while (url !== null) {
const response = await fetch(url, { headers });
if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
const page = await response.json();
for (const event of page.data) console.log(event.id, event.type, event.status);
url = page.links.next === null ? null : new URL(page.links.next, url);
}Consistency
A cursor is a position in descending ID order, not a snapshot of the list.
- Items created after the first request have higher IDs than the cursor. A walk that has started doesn't return them.
- An event is listed only after PayloadPuffin has stored it, which follows the
202response by a short delay. An event accepted before the walk started can be stored after the walk passed its position, and is then not returned. - A filter is evaluated when each page is requested. An item whose
statuschanges during a walk can be missing from, or appear in, a later page.
Resource IDs describes ID order.