Get bulk operation by ID

get/v1/bulk/{id}
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 one bulk operation by the id returned when you submitted it. This endpoint returns the status and details of that operation.

Status Values

  • queued - Accepted and waiting to be processed. You can submit many jobs and leave them queued. This response is the status for the single id in the path, so poll this endpoint for each id until its status moves on.
  • running - A worker is processing this operation.
  • complete - Processing has finished.

Getting Detailed Results

For comprehensive details about batch processing, including individual object IDs created during bulk operations, use the /v1/bulk/{id}/batches endpoint. This is particularly useful for bulk create operations where you need to retrieve the IDs of newly created objects.

Alternative Approach for Bulk Creates

When performing bulk create operations, consider including an externalId for each object. Once the bulk operation status is complete, you can perform lookups using the external IDs to retrieve the corresponding internal object IDs. This approach provides more reliable object tracking across bulk operations.

Response Field Details

  • batches.complete - Number of batches that have finished processing
  • batches.total - Total number of batches created for this operation
  • completedAt - Timestamp when the bulk operation finished

Common Usage

  1. Submit one or more bulk jobs (for example POST /v1/customers/bulk). Each response includes a bulk operation id. Store it.
  2. For each stored id, poll GET /v1/bulk/{id} until status is complete. Jobs move from queued to running to complete on their own, so one job staying queued does not block submitting or checking the others.
  3. Use GET /v1/bulk/{id}/batches to get detailed results and object IDs.
  4. For failed items, check batch errors for specific failure reasons

Performance Notes

  • Large bulk operations are processed in batches of up to 100 items each
  • Processing time varies based on operation type and data complexity
  • Poll interval recommendation: every 5-10 seconds for active operations

Error Handling

When batchErrors is true:

  • Check lastBatchError for the most recent failure details
  • Use the batches endpoint to identify which specific items failed
  • Check individual batch success/failure counts for detailed results

Related Endpoints

  • GET /v1/bulk/{id}/batches - Get detailed batch processing results
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 of results to return.

Example 1
pageSizeinteger

Number of results to return per page.

Example 100

Responses

OK

objectrequired