Returning.AIDevelopers
v1

API reference / Bulk Operations

.md

Get bulk update job status

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

Last updated 26 Sep 2026API v1

Method
GET
Path
https://api.returning.ai/v1/users/bulk-update/{id}/status
Permission
getBulkUpdate
Retries
Read-only; poll with backoff

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.

Authentication#

Header
Authorization: Bearer <API_KEY>
Permission
getBulkUpdateShown in the dashboard as “Get Bulk Update History”

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.
  • 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.

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

Request#

Path parameters#

id#stringREQUIRED
The job's _id from List bulk update jobs.

Rule24 hex characters

Eg"66f000000000000000000701"

Headers#

Authorization#stringREQUIRED
Community API key with getBulkUpdate.

RuleBearer <API_KEY>

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.

status#stringALWAYS
Result of the request.

Rulesuccess

message#stringALWAYS
Human-readable summary. Do not branch on it.
data#objectALWAYS
The job's state.
status#stringALWAYS
Where the job is. Completed can still include failed rows; Failed usually means the whole file was rejected.

RuleIn Queue, In Progress, Completed or Failed

successfulUsers#integer
Rows with no errors. Only when Completed.
failedUsers#integer
Rows with at least one error. Only when Completed.
receivedTime#stringALWAYS
When the job last moved to a new stage, ISO 8601 UTC. It is the upload time only while the job is In Queue.
duration#string
Processing time in seconds, as text. Only when Completed.

Eg"4.213 seconds"

{
  "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 request03

400Fix the request
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.
401AUTHENTICATION_REQUIREDFix the request
The key is missing, invalid or expired. Send Authorization: Bearer <API_KEY> with a current Community API key.
403API_KEY_PERMISSION_DENIEDFix the request
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 data02

500Fix the data
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.
404COMMUNITY_NOT_FOUNDFix the data
The community this key belongs to no longer exists. Contact Returning.AI support.

Retry with backoff01

500AUTHENTICATION_FAILEDRetry with backoff
The key could not be checked. Retry with backoff; nothing was read.
{
  "status": "fail",
  "message": "Bulk update ID is required and must be a valid ObjectId"
}

Next step#

Get bulk update job detailsGET/v1/users/bulk-update/{id}/detailsWhen the job is Completed, read each row's result and the reasons for any failed rows.