# Get bulk operation by ID

> GET /v1/bulk/{id} · Core resources API

Source: https://developer.kustomer.com/api/core-resources/get-bulk-operation-by-id

```http
GET https://{orgname}.api.kustomerapp.com/v1/bulk/{id}
Authorization: Bearer <API key>
```

## Authorization

Requires any one of these roles: `org.permission.bulk.read`; or legacy `org.user.bulk.read`. The API key or user must hold at least one of them. Legacy roles predate permission sets and still work.

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 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}`](https://developer.kustomer.com/api/core-resources/get-bulk-operation-by-id) |
| Get per-record results, new record IDs and errors | [`GET /v1/bulk/{id}/batches`](https://developer.kustomer.com/api/core-resources/get-bulk-operation-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`.

Related: [Bulk operations guide](https://developer.kustomer.com/docs/guides/bulk-operations), [Bulk customers](https://developer.kustomer.com/api/core-resources#customers-bulk), [Rate limits](https://developer.kustomer.com/docs/concepts/rate-limits)

### Recipes

#### 1. Import customers and collect their new IDs

Load up to 100 customers from another system in one request, wait for the job, then map each source row to the Kustomer ID it became.

**Step 1.** [`POST /v1/customers/bulk`](https://developer.kustomer.com/api/core-resources/bulk-create-customers.md). Send an array of up to 100 customers. Give every item a `_clientRef`, such as your own row ID, so you can match results back later; if any item has one, they all must, and each must be unique in the request. An `externalId` lets you look the customers up afterwards too. Keep the bulk operation's `id` from the response.

```bash title="cURL"
curl --request POST "https://api.kustomerapp.com/v1/customers/bulk" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '[
    {"_clientRef": "crm-001", "externalId": "crm-001", "name": "Alice Smith", "emails": [{"type": "home", "email": "alice@example.com"}]},
    {"_clientRef": "crm-002", "externalId": "crm-002", "name": "Bob Jones", "emails": [{"type": "home", "email": "bob@example.com"}]}
  ]'
```

```bash title="kusty"
BULK_ID=$(kusty api POST /v1/customers/bulk --data @customers.json | jq -r '.data.id')
```

**Step 2.** [`GET /v1/bulk/{id}`](https://developer.kustomer.com/api/core-resources/get-bulk-operation-by-id.md). Poll every 5 to 10 seconds until `status` is `complete`. The customers don't exist until the job has run, so don't read them back before then. Each poll counts against your rate limit.

```bash title="cURL"
curl "https://api.kustomerapp.com/v1/bulk/$BULK_ID" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```

```bash title="kusty"
until [ "$(kusty api GET /v1/bulk/$BULK_ID | jq -r '.data.attributes.status')" = complete ]; do sleep 10; done
```

**Step 3.** [`GET /v1/bulk/{id}/batches`](https://developer.kustomer.com/api/core-resources/get-bulk-operation-batches.md). Read the batches. Each `results` entry pairs your `_clientRef` with a `status` of `created` or `error`, plus the new `objectId` or an `error` reason. Without `_clientRef`, you only get `objectIds` and `errors`, which are harder to match to rows.

```bash title="cURL"
curl "https://api.kustomerapp.com/v1/bulk/$BULK_ID/batches" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```

```bash title="kusty"
kusty api GET /v1/bulk/$BULK_ID/batches --all \
  | jq -r '(.data.attributes.results // [])[] | [._clientRef, .status, (.objectId // .error)] | @tsv' > results.tsv
```

> `complete` means processing ended, not that every row succeeded: check `batchErrors` on the job, or the `error` rows in the results. The [bulk operations guide](https://developer.kustomer.com/docs/guides/bulk-operations) lists every bulk endpoint.

#### 2. Resubmit only the rows that failed

After a bulk job completes with errors, fix and resend just the failed rows instead of the whole file.

**Step 1.** [`GET /v1/bulk/{id}/batches`](https://developer.kustomer.com/api/core-resources/get-bulk-operation-batches.md). List the finished batches and collect the `_clientRef` and `error` of every result with `status` `error`.

```bash title="cURL"
curl "https://api.kustomerapp.com/v1/bulk/$BULK_ID/batches?completed=true" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```

```bash title="kusty"
kusty api GET /v1/bulk/$BULK_ID/batches --query completed=true --all \
  | jq -c '(.data.attributes.results // [])[] | select(.status == "error") | {_clientRef, error}' > failed.jsonl
```

**Step 2.** Pick the failed rows out of the file you sent, using `_clientRef`. Read each `error` first: a row that failed as a duplicate won't succeed by sending it again, so look that record up by `externalId` instead.

```bash title="kusty"
jq --slurpfile failed failed.jsonl \
  '[.[] | select(._clientRef as $ref | any($failed[]; ._clientRef == $ref))]' customers.json > retry.json
```

**Step 3.** [`POST /v1/customers/bulk`](https://developer.kustomer.com/api/core-resources/bulk-create-customers.md). Submit the corrected rows as a new job, keeping their `_clientRef`s, and follow it like the first one.

```bash title="cURL"
curl --request POST "https://api.kustomerapp.com/v1/customers/bulk" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY" \
  --header "Content-Type: application/json" \
  --data @retry.json
```

```bash title="kusty"
kusty api POST /v1/customers/bulk --data @retry.json --fields id
```

#### 3. Create conversations once their customers exist

Import records that depend on each other, such as customers and then their conversation history, by waiting for the first job before starting the second.

**Step 1.** [`GET /v1/bulk/{id}`](https://developer.kustomer.com/api/core-resources/get-bulk-operation-by-id.md). Wait for the customer job to reach `complete`. A conversation needs its customer's Kustomer ID, and that only exists once the customer job has run.

```bash title="cURL"
curl "https://api.kustomerapp.com/v1/bulk/$CUSTOMER_BULK_ID" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```

```bash title="kusty"
until [ "$(kusty api GET /v1/bulk/$CUSTOMER_BULK_ID | jq -r '.data.attributes.status')" = complete ]; do sleep 10; done
```

**Step 2.** [`GET /v1/bulk/{id}/batches`](https://developer.kustomer.com/api/core-resources/get-bulk-operation-batches.md). Map each `_clientRef` to the customer's new `objectId`, skipping rows that failed.

```bash title="cURL"
curl "https://api.kustomerapp.com/v1/bulk/$CUSTOMER_BULK_ID/batches" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```

```bash title="kusty"
kusty api GET /v1/bulk/$CUSTOMER_BULK_ID/batches --all \
  | jq -s '[.[] | (.data.attributes.results // [])[] | select(.status == "created") | {key: ._clientRef, value: .objectId}] | from_entries' > customer-ids.json
```

**Step 3.** Build the conversations from your source data, setting `customer` to the mapped ID; `customer` is required on every item. In this example each source row has its own `ref`, a `subject`, and `customerRef`, the `_clientRef` its customer was imported with. Rows whose customer failed are left out.

```bash title="kusty"
jq --slurpfile ids customer-ids.json \
  '[.[] | select($ids[0][.customerRef]) | {_clientRef: .ref, externalId: .ref, name: .subject, customer: $ids[0][.customerRef]}]' \
  source-conversations.json > conversations.json
```

**Step 4.** [`POST /v1/conversations/bulk`](https://developer.kustomer.com/api/core-resources/bulk-create-conversations.md). Submit the conversations as a second job and follow it the same way.

```bash title="cURL"
curl --request POST "https://api.kustomerapp.com/v1/conversations/bulk" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY" \
  --header "Content-Type: application/json" \
  --data @conversations.json
```

```bash title="kusty"
kusty api POST /v1/conversations/bulk --data @conversations.json --fields id
```

### Example object

A real record from [`GET /v1/bulk/{id}`](https://developer.kustomer.com/api/core-resources/get-bulk-operation-by-id.md):

```json
{
  "type": "bulk",
  "id": "507f1f77bcf86cd799439011",
  "attributes": {
    "context": "api.sobjects.customers.bulk-create",
    "status": "complete",
    "completed": true,
    "completedAt": "2023-12-01T10:05:00.000Z",
    "batchErrors": false,
    "v2": true,
    "createdAt": "2023-12-01T10:00:00.000Z",
    "updatedAt": "2023-12-01T10:05:00.000Z",
    "batches": {
      "complete": 1,
      "total": 1,
      "idsTotal": 3
    },
    "payload": {
      "api": {
        "method": "POST",
        "service": "api",
        "path": "/v1/customers",
        "requestId": "507f1f77bcf86cd799439012",
        "user": {
          "id": "507f1f77bcf86cd799439013",
          "userType": "user",
          "roles": [
            "org"
          ],
          "orgName": "example-org",
          "subject": "507f1f77bcf86cd799439013",
          "org": "507f1f77bcf86cd799439014"
        },
        "data": [
          {
            "name": "John Smith",
            "externalId": "customer_001"
          },
          {
            "name": "Sarah Johnson",
            "externalId": "customer_002"
          },
          {
            "name": "Michael Brown",
            "externalId": "customer_003"
          }
        ]
      }
    }
  },
  "relationships": {
    "org": {
      "links": {
        "self": "/v1/orgs/507f1f77bcf86cd799439014"
      },
      "data": {
        "type": "org",
        "id": "507f1f77bcf86cd799439014"
      }
    },
    "createdBy": {
      "links": {
        "self": "/v1/users/507f1f77bcf86cd799439013"
      },
      "data": {
        "type": "user",
        "id": "507f1f77bcf86cd799439013"
      }
    }
  },
  "links": {
    "self": "/v1/bulk/507f1f77bcf86cd799439011"
  }
}
```

Fields:

- `id` (string): The ID the bulk request returned. Keep it to poll `GET /v1/bulk/{id}` and read the job's batches.
- `attributes.context` (string): Which kind of bulk request started the job, such as a bulk customer create.
- `attributes.status` (string): `queued`, `running` or `complete`. A job moves through them on its own; poll until it's `complete`.
- `attributes.completed` (boolean): `true` once processing has ended. It doesn't mean every record succeeded; check `batchErrors`.
- `attributes.completedAt` (string (date-time)): When processing ended. Not set while the job is queued or running.
- `attributes.batchErrors` (boolean): `true` if any batch had a failure. The [batches](https://developer.kustomer.com/api/core-resources/get-bulk-operation-batches) say which records failed and why.
- `attributes.batches` (object): Progress: `complete` out of `total` batches have finished. Batches hold up to 100 items, so a single bulk request is usually one batch.
- `attributes.payload.api` (object): The request that created the job: its `method`, `path` and the records you sent in `data`.
- `attributes.payload.api.user` (object): The user or API key that submitted the request, with its roles at the time.
- `attributes.payload.api.data` (array): The records exactly as you sent them. For the IDs of created records, read the batches' `objectIds` or `results`.

### Permissions

Fewest roles for a read-only integration: `org.permission.bulk.read`. For every endpoint: `org.permission.bulk.read`.

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | Resource ID. |

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `page` | integer | no | Page number of results to return. |
| `pageSize` | integer | no | Number of results to return per page. |

## Responses

### 200

OK

- `data` (object, required)
  - `type` (string, required): One of: `bulk`.
  - `id` (string, required)
  - `attributes` (object, required)
    - `ids` (array<string>)
    - `search` (string)
    - `context` (string, required)
    - `status` (string, required): One of: `queued`, `running`, `complete`.
    - `errors` (object)
    - `batchErrors` (boolean)
    - `lastBatchError` (object)
    - `completed` (boolean, required)
    - `completedAt` (string<date-time>)
    - `isLarge` (boolean)
    - `v2` (boolean, required)
    - `batches` (object)
    - `retentionPolicyRunId` (string)
    - `payload` (object)
    - `createdAt` (string<date-time>, required)
    - `updatedAt` (string<date-time>, required)
  - `relationships` (object, required)
    - `org` (object, required)
    - `createdBy` (object)
  - `links` (object, required)
    - `self` (string, required)

```json
{
  "data": {
    "type": "bulk",
    "id": "507f1f77bcf86cd799439011",
    "attributes": {
      "context": "api.sobjects.customers.bulk-create",
      "status": "complete",
      "completed": true,
      "completedAt": "2023-12-01T10:05:00.000Z",
      "batchErrors": false,
      "v2": true,
      "createdAt": "2023-12-01T10:00:00.000Z",
      "updatedAt": "2023-12-01T10:05:00.000Z",
      "batches": {
        "complete": 1,
        "total": 1,
        "idsTotal": 3
      },
      "payload": {
        "api": {
          "method": "POST",
          "service": "api",
          "path": "/v1/customers",
          "requestId": "507f1f77bcf86cd799439012",
          "user": {
            "id": "507f1f77bcf86cd799439013",
            "userType": "user",
            "roles": [
              "org"
            ],
            "orgName": "example-org",
            "subject": "507f1f77bcf86cd799439013",
            "org": "507f1f77bcf86cd799439014"
          },
          "data": [
            {
              "name": "John Smith",
              "externalId": "customer_001"
            },
            {
              "name": "Sarah Johnson",
              "externalId": "customer_002"
            },
            {
              "name": "Michael Brown",
              "externalId": "customer_003"
            }
          ]
        }
      }
    },
    "relationships": {
      "org": {
        "links": {
          "self": "/v1/orgs/507f1f77bcf86cd799439014"
        },
        "data": {
          "type": "org",
          "id": "507f1f77bcf86cd799439014"
        }
      },
      "createdBy": {
        "links": {
          "self": "/v1/users/507f1f77bcf86cd799439013"
        },
        "data": {
          "type": "user",
          "id": "507f1f77bcf86cd799439013"
        }
      }
    },
    "links": {
      "self": "/v1/bulk/507f1f77bcf86cd799439011"
    }
  }
}
```

### 400

Bad Request

### 401

Unauthorized

### 403

Forbidden

### 404

Not Found

## Example request

```bash
curl --request GET \
  --url 'https://api.kustomerapp.com/v1/bulk/62799c44a96e7f160834199c' \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```