Get bulk operation batches

get/v1/bulk/{id}/batches
Requires any one of these rolesAbout roles
org.permission.bulk.read
Legacyorg.user.bulk.read

The API key or user must hold at least one of them. Legacy roles still work; prefer the others for new keys.

Retrieves detailed batch information for a specific bulk operation, including individual object IDs created or processed during the operation. This endpoint provides comprehensive details about each batch within a bulk operation.

Use Cases

  • Retrieve object IDs of newly created entities from bulk create operations
  • Get detailed error information for failed batch items
  • Monitor individual batch processing status and completion times
  • Access success/failure counts at the batch level

Batch Status Values

  • queued - Batch is waiting to be processed
  • scheduled - Batch has been scheduled for processing
  • complete - Batch processing has finished

Response Details

Each batch includes:

  • objectIds - Array of IDs for successfully created/updated objects
  • successCount - Number of items processed successfully in this batch
  • failureCount - Number of items that failed in this batch
  • completedAt - Timestamp when batch processing finished
  • errors - Detailed error information for failed items
  • results - Per-item correlation array (only present when _clientRef was supplied on the original request). Each entry contains:
    • _clientRef — the token you supplied on that request item
    • status — "created", "updated", or "error"
    • objectId — ID of the created/updated object; omitted on error entries
    • error — failure reason; present only when status is "error"

Sorting and Filtering

  • Sorting: Supports sorting by createdAt field
    • sort=createdAt - Sort by creation time (ascending, oldest first)
    • sort=-createdAt - Sort by creation time (descending, newest first)
    • Default: createdAt ascending (oldest first)
  • Status Filtering: Filter by batch status (queued, scheduled, complete)
  • Completion Filtering: Filter by completion state (true/false)

Pagination

Results are paginated. Use standard pagination parameters (page, limit) to navigate through large batch lists.

About this resource

Bulk operations

A bulk operation is the background job Kustomer creates when you create, update or delete many records in one bulk request. You poll it to see when the job finishes, then read its batches to find out which records succeeded and which failed.

Bulk endpoints such as POST /v1/customers/bulk, PUT /v1/conversations/bulk and DELETE /v1/klasses/{name}/bulk accept up to 100 records per request, but they don't do the work while you wait. They validate the request, queue the work, and respond right away with a bulk operation (type bulk) whose id you keep. Kustomer then processes the records in the background. The two endpoints here are how you follow that job: one for its overall status, one for per-record results. The records themselves are only created, updated or deleted once the job has run, so don't read them back straight after the bulk request returns.

Job status

status Meaning
queued Accepted and waiting. You can submit many jobs and leave them queued.
running Being processed.
complete Finished. completed is true and completedAt is set.

A job moves through these on its own; one job sitting in queued doesn't stop you submitting or checking others. While it runs, batches.complete out of batches.total shows progress. complete means processing has ended, not that every record succeeded: batchErrors is true if any batch had failures, and lastBatchError holds the most recent one.

Batches and per-record results

Kustomer splits each job into batches of up to 100 items, each with its own status (queued, scheduled or complete), successCount and failureCount. A batch has three ways to tell you what happened to individual records:

  • objectIds lists the IDs of records that were created or updated successfully. This is how you get the IDs of new records from a bulk create.
  • errors gives details for items that failed.
  • results appears only if you sent _clientRef on every item of the original request. Each entry pairs your _clientRef with a status of created, updated or error, plus the objectId on success or an error reason on failure. This is the most reliable way to match outcomes back to your source rows.

If you also set externalId on the records you create, you can look them up by that ID once the job is complete, long after the batch results stop being convenient.

Which endpoint to use

To Call
Check whether a bulk job has finished GET /v1/bulk/{id}
Get per-record results, new record IDs and errors GET /v1/bulk/{id}/batches, with status or completed to filter and sort=-createdAt for newest first

Poll GET /v1/bulk/{id} every 5 to 10 seconds with backoff until status is complete, then read the batches. Each poll counts against your rate limit, while a whole bulk request counts as one call, so polling sensibly keeps bulk far cheaper than single-record calls. When records depend on each other, such as customers and then their conversations, wait for one job to complete before you submit the next. The batch list is paginated with page and limit.

RelatedBulk operations guideBulk customersRate limits

Path parameters

idstringrequired

Resource ID.

Example "62799c44a96e7f160834199c"

Query parameters

pageinteger

Page number for pagination

Default 1Example 1
sortstring

Sort field and direction. Only supports createdAt. Use "createdAt" for ascending or "-createdAt" for descending. Defaults to createdAt ascending.

One ofcreatedAt-createdAtDefault "createdAt"Example "-createdAt"
statusstring

Filter batches by status

One ofqueuedscheduledcompleteExample "complete"
completedstring

Filter batches by completion status

One oftruefalseExample "true"
limitinteger

Number of results per page

Default 25Example 25
pageSizeinteger

Number of results to return per page.

Example 100

Responses

OK

array<object>
object