Skip to content
PayloadPuffin.
Join the waitlist

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

OperationFiltersOrder
List eventsstatus, destinationIdNewest first
List deliveriesstatus, eventId, destinationIdNewest 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

JSON
{
	"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.

FieldTypeDescription
dataarrayThe items in this page
links.nextstring or nullA query string that requests the next page. null on the last page.

Query parameters

ParameterTypeDefaultDescription
limitnumber100Items per page, from 1 to 100
cursorIDNoneReturn 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.

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.

Requestlinks.nextNext 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.

list-events.mjs
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 202 response 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 status changes during a walk can be missing from, or appear in, a later page.

Resource IDs describes ID order.