Returning.AIDevelopers
v1

API reference / Bulk Operations

.md

List bulk update jobs

List your community's bulk user update jobs, newest first, so you can find a job's ID by its log_name.

Last updated 26 Sep 2026API v1

Method
GET
Path
https://api.returning.ai/v1/users/bulk-update
Permission
getBulkUpdate
Retries
Read-only; exact retries are safe

When to use this

  • Find the _id of a job you just uploaded, by matching name to the log_name you sent.
  • After a timeout on an upload, check whether the job was created before you upload again.
  • Show recent bulk updates and their outcomes in your own tools.

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 only see that community's jobs.

Behaviour#

Bulk update users from CSV returns no job ID, so this list is how you find one. Jobs come back newest upload first. There is no filter or search: read from page 1 and match name to the log_name you sent. Names don't have to be unique, so give every upload its own log_name; if two jobs share one, the first match is the newer job.

The list holds jobs from Bulk update users from CSV only, whichever key in your community uploaded them. Premium currency uploads and legacy bulk imports are not listed.

Request#

Query parameters#

page#integerOPTIONAL
Page number, starting at 1.

RuleWhole number, 1 or more; default 1

Eg1

limit#integerOPTIONAL
Jobs per page.

RuleDefault 10; max 100

Eg20

Headers#

Authorization#stringREQUIRED
Community API key with getBulkUpdate.

RuleBearer <API_KEY>

curl --request GET \
  --url 'https://api.returning.ai/v1/users/bulk-update?page=1&limit=20' \
  --header 'Authorization: Bearer <API_KEY>'

Response#

A 200 returns the jobs in data.data and the totals in data.pagination. receivedAt changes as the job moves on, so don't use it as the upload time. For row counts, use Get bulk update job status.

If data.pagination is an empty object and data.data is empty, the list could not be read; retry with backoff.

status#stringALWAYS
Result of the request.

Rulesuccess

message#stringALWAYS
Human-readable summary. Do not branch on it.
data#objectALWAYS
Paging totals and this page of jobs.
pagination#objectALWAYS
Paging totals for all your jobs. An empty object means the list could not be read; retry.
total#integer
Jobs across all pages.
totalPages#integer
Pages at this limit. 0 when there are no jobs.
currentPage#integer
The page you asked for.
hasNextPage#boolean
true when a later page has jobs.
hasPrevPage#boolean
true when page is above 1.
data#object[]ALWAYS
Jobs on this page, newest upload first. Empty past the last page.
_id#string
The job ID. Send it to Get bulk update job status and details.
name#string
The log_name sent with the upload, or Bulk Update Users if none was sent.
status#string
Where the job is, in lower case.

Rulequeued, processing, completed or failed

receivedAt#string
When the job last moved to a new stage, ISO 8601 UTC. It is the upload time only while the job is queued.
duration#string
Processing time in seconds, as text, such as "4.213". Left out until the job finishes.
{
  "status": "success",
  "message": "All bulk updates fetched successfully",
  "data": {
    "pagination": {
      "total": 2,
      "totalPages": 1,
      "currentPage": 1,
      "hasNextPage": false,
      "hasPrevPage": false
    },
    "data": [
      {
        "_id": "66f000000000000000000701",
        "receivedAt": "2026-09-26T02:00:05.000Z",
        "duration": "4.213",
        "status": "completed",
        "name": "Coins top-up 2026-09-26"
      },
      {
        "_id": "66f000000000000000000702",
        "receivedAt": "2026-09-25T02:00:03.000Z",
        "duration": "0.512",
        "status": "failed",
        "name": "Coins top-up 2026-09-25"
      }
    ]
  }
}

Errors#

The 401, 403 and 404 errors, and 500 AUTHENTICATION_FAILED, come from the API key check and carry the code in meta.code. A 400 has no code; detail names the query field.

Fix the request03

400Fix the request
limit is over 100, or page or limit is not a number. There is no code; detail names the field. Send page of 1 or more and limit up to 100.
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 data01

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.
{
  "meta": {
    "status": "error",
    "statusCode": 400
  },
  "message": "Get all bulk update endpoint validation error.",
  "detail": {
    "limit": "Limit must be less than 100"
  },
  "solution": "Check your query in request and try again"
}

Next step#

Get bulk update job statusGET/v1/users/bulk-update/{id}/statusPoll the job's _id until it is Completed or Failed.