Skip to content

Requests and responses

Pagination

Read long lists a page at a time with cursors.

Cursor pagination

List endpoints return one page at a time. The response's links object has self, next and prev. To get the next page, request the next link exactly as it is. It repeats your filter, sort and fields and adds a page[cursor]. On the last page next is null, and on the first page so is prev.

json
"links": {
  "self": "https://email.growthdept.ai/api/profiles?page[size]=20",
  "next": "https://email.growthdept.ai/api/profiles?page[size]=20&page[cursor]=eyJ2Ijoi...",
  "prev": null
}

Page size

Set page[size] to choose how many resources come back, within each endpoint's range. Out of range returns 400 invalid on page[size].

EndpointDefault sizeLargest size
GET /api/campaign-messages20100
GET /api/campaigns100100
GET /api/campaigns/{id}/campaign-messagesFixedFixed
GET /api/catalog-categories100100
GET /api/catalog-category-bulk-create-jobsFixedFixed
GET /api/catalog-category-bulk-delete-jobsFixedFixed
GET /api/catalog-category-bulk-update-jobsFixedFixed
GET /api/catalog-item-bulk-create-jobsFixedFixed
GET /api/catalog-item-bulk-delete-jobsFixedFixed
GET /api/catalog-item-bulk-update-jobsFixedFixed
GET /api/catalog-items100100
GET /api/catalog-variant-bulk-create-jobsFixedFixed
GET /api/catalog-variant-bulk-delete-jobsFixedFixed
GET /api/catalog-variant-bulk-update-jobsFixedFixed
GET /api/catalog-variants100100
GET /api/catalog-categories/{id}/items100100
GET /api/catalog-items/{id}/categories100100
GET /api/catalog-items/{id}/variants100100
GET /api/catalog-categories/{id}/relationships/items100100
GET /api/catalog-items/{id}/relationships/categories100100
GET /api/catalog-items/{id}/relationships/variants100100
GET /client/geofences20100
GET /client/review-values-reports20100
GET /client/reviews20100
GET /api/coupon-code-bulk-create-jobsFixedFixed
GET /api/coupon-codes100100
GET /api/coupons100100
GET /api/coupons/{id}/coupon-codes100100
GET /api/coupons/{id}/relationships/coupon-codes100100
GET /api/data-sources20100
GET /api/object-types/{id}/object-ingestion-logsFixedFixed
GET /api/object-types/{id}/object-records20100
GET /api/object-types/{id}/relationships/object-ingestion-logsFixedFixed
GET /api/object-types/{id}/relationships/object-records20100
GET /api/events2001000
GET /api/flows5050
GET /api/flow-actions/{id}/flow-messages5050
GET /api/flows/{id}/flow-actions5050
GET /api/flow-actions/{id}/relationships/flow-messages5050
GET /api/flows/{id}/relationships/flow-actions5050
GET /api/forms20100
GET /api/forms/{id}/form-versions20100
GET /api/forms/{id}/relationships/form-versions20100
GET /api/images20100
GET /api/lists1010
GET /api/lists/{id}/profiles20100
GET /api/lists/{id}/relationships/profiles20100
GET /api/metricsFixedFixed
GET /api/profile-bulk-import-jobs20100
GET /api/profile-suppression-bulk-create-jobsFixedFixed
GET /api/profile-suppression-bulk-delete-jobsFixedFixed
GET /api/profiles20100
GET /api/push-tokens20100
GET /api/profile-bulk-import-jobs/{id}/import-errors20100
GET /api/profile-bulk-import-jobs/{id}/profiles20100
GET /api/profile-bulk-import-jobs/{id}/relationships/profiles20100
GET /api/reviews20100
GET /api/segments1010
GET /api/segments/{id}/profiles20100
GET /api/segments/{id}/relationships/profiles20100
GET /api/tag-groups2525
GET /api/tags5050
GET /api/template-universal-content20100
GET /api/templates1010
GET /api/text-messaging-senders1020
GET /api/tracking-settingsFixedFixed
GET /api/translations20100
GET /api/web-feeds520

About cursors

  • Treat a cursor as opaque. It encodes where the page ends and is signed, so an edited cursor returns 400 invalid on page[cursor].
  • A cursor belongs to the sort it was made with. Changing sort while keeping the cursor is refused the same way.
  • Pages are keyed on the sort value and the id, so resources added or removed while you page through do not make you skip or repeat others.

Reading every page

Node
let url = "https://email.growthdept.ai/api/profiles?page[size]=100";
const headers = {
  Authorization: `Klaviyo-API-Key ${process.env.GD_EMAIL_PRIVATE_KEY}`,
  accept: "application/vnd.api+json",
  revision: "2026-10-15",
};
while (url) {
  const res = await fetch(url, { headers });
  if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);
  const page = await res.json();
  for (const profile of page.data) {
    // use profile.id and profile.attributes
  }
  url = page.links.next;
}