Bulk and Batch Requests

The cost of one at a time

Sending a separate request for every single record adds up far faster than it first appears. Each individual call carries its own connection setup, authentication, headers, and round-trip latency, and each one also counts against your rate-limit allowance. When you are processing hundreds or thousands of records, that per-request overhead can easily come to dominate the actual useful work being done.

Bulk and batch techniques exist precisely to amortise this cost, by handling many items within a single request instead of one each. Fewer calls means dramatically less overhead, far fewer round trips across the network, and much gentler pressure on your rate-limit budget — often the difference between a job that finishes comfortably and one that constantly trips throttles.

Bulk versus batch

The two terms overlap in everyday speech but differ meaningfully in shape, and it helps to keep them distinct. A bulk endpoint accepts many items of the same kind within one request — create or update a whole list of records in a single call. Batching, by contrast, bundles several distinct operations together, possibly spanning different endpoints, into one envelope that the server then unpacks and runs.

POST /v1/customers/bulk
{ "records": [ { ... }, { ... }, { ... } ] }

Bulk suits homogeneous workloads such as importing a long list of identical records; batching suits a mixed sequence of related but different calls. Which of the two an API offers, and in what exact form, varies considerably, so check its documentation carefully before designing your integration around either approach.

Partial success

The genuinely subtle part of batching is that some items within a single request can succeed while others in the same request fail. A thoughtfully designed API returns a per-item result for exactly this reason, so you can see precisely which records went through and which did not, rather than collapsing everything into one blunt all-or-nothing status that hides the detail you need.

Read those per-item results carefully and act on them individually. Map each outcome back to the specific item you sent, retry only the genuine failures rather than the whole batch, and never assume an overall 200 means every item inside succeeded. The envelope may well report individual errors nested inside an otherwise perfectly successful response, and missing them leads to silent data loss.

Respecting limits

Bulk operations almost always cap how many items a single request may contain. Exceed that documented ceiling and the entire call is rejected outright, so you must split very large jobs into chunks that each comfortably fit the maximum and then process those chunks in sequence one after another.

Choose a chunk size that deliberately balances efficiency against reliability. It should be large enough to cut the per-request overhead meaningfully, yet small enough that a single failure or a timeout midway through does not force you to redo an enormous amount of work that had already succeeded. Keep an eye on total payload size as well as raw item count, since some limits are expressed in bytes rather than records.

Batch or parallel

Where no bulk or batch endpoint exists at all, carefully controlled parallel requests can still speed things up considerably — but only if you stay within the rate limits and firmly cap your concurrency, so you do not accidentally trigger a wave of 429 responses that leaves you worse off than serial calls would have. A genuine bulk endpoint is almost always the more efficient choice when one is available to you.

To keep that parallel work safely under control and avoid tripping limits, read rate limiting explained, which covers concurrency, backoff, and pacing in the depth this needs.