# Choosing between APIs, exports, and bulk operations in Kustomer

> Integrations and internal tools often need large amounts of data from Kustomer Depending on what you are doing the right path may be the  REST API  an  expor

Source: https://help.kustomer.com/en_us/apis-exports-and-bulk-operations-in-kustomer-SJNnhJlAZx

Last updated: 2026-04-29T20:59:04.010Z

Integrations and internal tools often need large amounts of data from Kustomer. Depending on what you are doing, the right path may be the **REST API**, an **export**, or **bulk work** in the product or through the API. This article explains how to think about those choices, how pagination and payload size interact with reliability, and where to look for endpoint-specific rules.

Use this guide together with the [**Kustomer API reference**](https://developer.kustomer.com/) for the resources you call. Pagination parameter names, defaults, maximum page sizes, and completion signals **vary by endpoint**; the API reference is the source of truth for each route.

### In this article

*   [Choose the right retrieval or update path](#retrieval)
*   [When to use the API](#api)
*   [When to use exports](#exports)
*   [When to use bulk operations](#bulk)
*   [Pagination and knowing when you are done](#pagination)
*   [Payload size and performance tradeoffs](#payload)
*   [Expected behavior during long runs](#behavior)
*   [Best practices for large reads and writes](#best-practices)

### Choosing the right retrieval or update path

**To pick a starting approach**

1.  Decide whether you need **interactive, filtered, or near-real-time** access (often the API), a **large static extract** for reporting or archival (often exports), or **batch-style updates** across many records (bulk operations in the product or carefully designed API usage).
2.  Open the **API reference** for each endpoint you plan to use and note which pagination parameters that endpoint accepts, what the response body returns for **next page** or **totals**, and any limits on page size or rate. For example, some v2 endpoints allow `pageSize` up to 1000, while some AI endpoints cap `pageSize` at 250.
3.  For exports, follow the export or reporting workflow your organization uses in Kustomer and the related documentation for job status and file delivery.

### When to use the API

The API fits well when you need **programmatic** access, **incremental** syncs, **filtering**, **field selection**, or **moderate** result sets where you can page through responses in a controlled way. Use it for integrations that react to events, keep another system in sync, or power internal tools that query recent or scoped data.

Because pagination and completion metadata differ by endpoint, treat each integration as **endpoint-specific**: confirm parameter names (for example `page` and `pageSize` on some resources), how the response signals another page, and recommended caps from the reference for that route.

### When to use exports

Exports fit **large historical pulls**, **reporting**, **offline analysis**, and jobs where **completeness** and a **stable file or job result** matter more than lowest latency. Prefer exports over deep interactive paging when you would otherwise issue a very long sequence of API calls across a huge dataset.

### When to use bulk operations

**Bulk operations** in this sense means **high-volume changes** or administrative batch work—either through **in-app** flows designed for admins (where your product edition provides them) or through **documented API patterns** intended for batch updates. Not every resource has a dedicated bulk endpoint. 

Use in-app bulk paths when the product offers them for your task and they meet your scope; use the API when you need full control, automation, or fields and filters that the UI does not expose.

### Pagination and knowing when you are done

Kustomer APIs rely on **resource-specific** pagination. Most documented list endpoints use `page` and `pageSize`, but defaults, maximums, filters, response metadata, and completion signals vary by endpoint. Always check the API reference for the specific route you call.

**To paginate safely**

1.  In the **API reference**, locate the list or search operation you are calling.
2.  Note which query parameters control page size and cursor or offset, and which response fields indicate **additional pages** (for example flags or links for the next page, counters, or empty result pages).
3.  Stop when the endpoint’s documented completion condition is met. For many Kustomer list endpoints, this means `links.next` is `null`; some endpoints also provide `meta.total` and `meta.totalPages`.

Document for your own runbooks **how you detect the last page** for each endpoint your integration uses, so operators can troubleshoot “missing” rows or duplicate pages.

### Payload size and performance tradeoffs

**Smaller pages** usually mean more HTTP requests but lower risk of **timeouts**, **memory pressure**, and oversized responses. They also make **incremental** processing and **retries** easier.

**Larger pages** reduce request count but increase the size of each response and the work done per request. Very large pages can worsen latency and failure modes if the network or client is constrained.

**To balance payload size**

1.  Start with a **conservative** page size allowed by the endpoint and increase only if you measure a clear benefit.
2.  Request only the **fields and includes** you need if the API supports sparse fieldsets or related-resource controls for that route.
3.  For long historical windows, prefer **narrow filters** (for example date or updated-time ranges) in addition to paging.

### Expected behavior during long runs

Active data can **change while you paginate**: new records may appear, sort order may affect stability, and totals in metadata describe the response set at a point in time rather than a frozen snapshot. For **stable** large extracts, exports are usually easier to reason about than paging an entire history through a generic list API.

Use **stable sort keys** where the API allows ordering that supports repeatable paging, and design integrations to **retry with backoff** on transient errors.

**Plan for authentication, permissions, and rate limits** — handle `401`, `403`, `429`, and transient 5xx responses explicitly. Retry only idempotent or safely repeatable work, and use backoff for rate limits and temporary failures.

### Best practices for large reads and writes

*   **Read the endpoint contract first** — parameter names, defaults, and completion signals are defined per resource in the API reference.
*   **Prefer exports** for full-dataset or reporting-style extraction when that matches your operational model.
*   **Prefer smaller pages** for interactive UIs and incremental reads; tune upward only with measurement.
*   **Window large pulls** with time or update filters when the API supports them.
*   **Checkpoint** progress (last page, last cursor, last timestamp) so jobs can resume.
*   **Use bulk or export paths** for very large backfills instead of treating a single list API as an export substitute unless the reference recommends that pattern for your use case.
*   **Follow** `links.next` where present — do not infer completion only from the number of records returned unless the endpoint documents that behavior.
*   **Respect endpoint-specific caps** — page-size maximums vary; do not reuse one value globally.
*   **Make writes idempotent where possible** — large update jobs should be safe to retry without duplicating work or overwriting newer changes.