# Get bulk update job status

Check whether a bulk update job is queued, running or finished, with row counts once it completes.

- Endpoint: `GET https://api.returning.ai/v1/users/bulk-update/{id}/status`
- Section: Users and data / Bulk operations
- Authentication: `Authorization: Bearer <API_KEY>` (Community API key)
- Permission: `getBulkUpdate` (Shown in the dashboard as "Get Bulk Update History")
- Retries: Read-only; poll with backoff
- Guide: hand-written
- Verified: live, 2026-09-27
- Last updated: 26 Sep 2026
- Web page: https://docs.returning.ai/api-reference/bulk-operations/get-bulk-update-job-status

## When to use this

- Poll after a CSV upload until the job finishes.
- Show how many rows of a nightly feed succeeded and failed.
- Decide when to read row results, which are only ready once the job is `Completed`.

**Instead:** Use [Get bulk update job details](https://docs.returning.ai/api-reference/bulk-operations/get-bulk-update-job-details.md) instead to see which rows failed and why.

**Unknown ID:** An ID that matches no job in your community returns `500` with `detail` `Bulk update not found`, not `404`. Don't retry it; look the job up again.

## Authentication

- Header: `Authorization: Bearer <API_KEY>`
- Permission: `getBulkUpdate`

This endpoint needs `getBulkUpdate`, shown in the dashboard as Get Bulk Update History. Use a Community API key and keep it on your server. The key decides the community, so you can only read jobs from that community.

## Behaviour

A job starts `In Queue`, moves to `In Progress`, and ends `Completed` or `Failed`. Jobs for one community run one at a time, oldest first, so a job can wait `In Queue` behind earlier uploads.

- `Completed` means the job has finished, but some rows may have failed. `successfulUsers` and `failedUsers` count the rows; read the failed ones with [Get bulk update job details](https://docs.returning.ai/api-reference/bulk-operations/get-bulk-update-job-details.md).
- `Failed` usually means the whole file was rejected before any change, for example because of an unknown column. This endpoint does not return the reason; check the file against the rules in [Bulk update users from CSV](https://docs.returning.ai/api-reference/bulk-operations/bulk-update-users-from-csv.md).

Only `Completed` includes the counts and `duration`. The other states return `status` and `receivedTime` only.

## Request

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | Yes | The job's `_id` from List bulk update jobs. (24 hex characters) |

### Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | `string` | Yes | Community API key with `getBulkUpdate`. (`Bearer <API_KEY>`) |

### Example request

```bash
curl --request GET \
  --url https://api.returning.ai/v1/users/bulk-update/66f000000000000000000701/status \
  --header 'Authorization: Bearer <API_KEY>'
```

## Response

This endpoint uses title-case labels. List bulk update jobs shows the same states in lower case: `queued`, `processing`, `completed` and `failed`. The counts here are named `successfulUsers` and `failedUsers`; details names them `successUsers` and `failedUsers`.

### Response fields

| Field | Type | Presence | Description |
| --- | --- | --- | --- |
| `status` | `string` | always | Result of the request. (`success`) |
| `message` | `string` | always | Human-readable summary. Do not branch on it. |
| `data` | `object` | always | The job's state. |
| `data.status` | `string` | always | Where the job is. `Completed` can still include failed rows; `Failed` usually means the whole file was rejected. (`In Queue`, `In Progress`, `Completed` or `Failed`) |
| `data.successfulUsers` | `integer` | - | Rows with no errors. Only when `Completed`. |
| `data.failedUsers` | `integer` | - | Rows with at least one error. Only when `Completed`. |
| `data.receivedTime` | `string` | always | When the job last moved to a new stage, ISO 8601 UTC. It is the upload time only while the job is `In Queue`. |
| `data.duration` | `string` | - | Processing time in seconds, as text. Only when `Completed`. |

### Example response (200)

```json
{
  "status": "success",
  "message": "Bulk update status fetched successfully",
  "data": {
    "status": "Completed",
    "successfulUsers": 1,
    "failedUsers": 1,
    "receivedTime": "2026-09-26T02:00:05.000Z",
    "duration": "4.213 seconds"
  }
}
```

## Errors

The 401, 403 and 404 errors, and `500 AUTHENTICATION_FAILED`, come from the API key check and carry the code in `meta.code`. Other errors from this endpoint have no `code`, so branch on the HTTP status and, for a `500`, on `detail`.

### Fix the request

| Status | Code | What to do |
| --- | --- | --- |
| 400 | - | The ID is not a valid ID (message: `Bulk update ID is required and must be a valid ObjectId`). Send the job's 24-character `_id` from List bulk update jobs. |
| 401 | `AUTHENTICATION_REQUIRED` | The key is missing, invalid or expired. Send `Authorization: Bearer <API_KEY>` with a current Community API key. |
| 403 | `API_KEY_PERMISSION_DENIED` | The key lacks `getBulkUpdate`, or it is a personal key. Use a Community API key and add the permission in Settings > Integration > API Keys. |

### Fix the data

| Status | Code | What to do |
| --- | --- | --- |
| 500 | - | With `detail` `Bulk update not found`, the ID matches no job in your community: find the right `_id` with List bulk update jobs, and don't retry this one. Any other `detail` means the job could not be read; retry with backoff. |
| 404 | `COMMUNITY_NOT_FOUND` | The community this key belongs to no longer exists. Contact Returning.AI support. |

### Retry with backoff

| Status | Code | What to do |
| --- | --- | --- |
| 500 | `AUTHENTICATION_FAILED` | The key could not be checked. Retry with backoff; nothing was read. |

**Retries:** This endpoint is read-only, so polling it is safe. Poll with a growing delay rather than a tight loop. Don't upload the file again while the job is `In Queue` or `In Progress`: that creates a second job. Retry a network error or a 5xx with backoff, except a `500` with `detail` `Bulk update not found`. Over the [rate limit](https://docs.returning.ai/how-it-works.md#rate-limits), requests return `429`; wait for the window to reset, then retry.

## Next step

- [Get bulk update job details](https://docs.returning.ai/api-reference/bulk-operations/get-bulk-update-job-details.md): `GET /v1/users/bulk-update/{id}/details`. When the job is `Completed`, read each row's result and the reasons for any failed rows.
- [Job failed? Fix the file and upload it again with Bulk update users from CSV](https://docs.returning.ai/api-reference/bulk-operations/bulk-update-users-from-csv.md): `POST /v1/users/bulk-update`.