# Batch requests

Some methods are available in a batch version that can complete more than one operation in a single request. For example, you might use a batch request to update the information for a thousand users. Batch requests run in the background and clients query the API periodically to check the status of a batch request as well as query the API for the result when it is finished.

Each method's documentation will mention if it has a batch version available.

# Requests

# URL

https://customdomain.com/api/batch/{method}

# Request

The request is an array of valid inputs for the respective method. For example, /api/batch/user.update would accept the following request:

[
  {
    "user_id": "wLQPaRVUME7f",
    "first_name": "John"
  },
  {
    "user_id": "qwIHFEihqw15",
    "last_name": "Doe",
    "language": "en"
  }
]

# Response

A successful response will return the id for the batch request. It can be used to query the status of the batch request.

{
  "status": "success",
  "data": {
    "batch_id": "agDjGj24Gdjk"
  }
}

# Status

# URL

https://customdomain.com/api/batch.status

# Arguments

# Request

{
  "batch_id": "agDjGj24Gdjk"
}

# Response

There are three possible statuses for a batch request.

# Pending

The batch request has not yet started.

{
  "status": "success",
  "data": {
    "status": "pending"
  }
}

# Started

The batch request is in progress.

{
  "status": "success",
  "data": {
    "status": "started",
    "started_at": "2019-11-13T10:00:41.188Z",
    "total": 300,
    "success": 297,
    "error": 2
  }
}

# Finished

The batch request is finished so you are able to query the result with /api/batch.result.

{
  "status": "success",
  "data": {
    "status": "finished",
    "finished_at": "2019-11-13T10:00:41.188Z",
    "total": 300,
    "success": 298,
    "error": 2
  }
}

# Errors

# Result

# URL

https://customdomain.com/api/batch.result

# Arguments

# Request

{
  "batch_id": "agDjGj24Gdjk"
}

# Response

The result will for each request will be included in a list in the same order in which they were received. For example, the result for a batch of user.create requests could be:

{
  "status": "success",
  "data": [
    {
      "status": "success",
      "data": { "user_id": "wLQPaRVUME7f" }
    },
    {
      "status": "error",
      "error": "login_id_exists"
    },
    {
      "status": "success",
      "data": { "user_id": "FqhqHF24Ghks" }
    }
  ]
}

The size of this response can be quite large depending on the size of the batch request.

# Errors

# Limits

# Payload limit

Batch requests have a higher limit to the length of the request's body compared to regular requests. If any batch request payload exceeds 5MB, a 400 Bad Request will be returned, along with the following response:

{
  "status": "error",
  "error": "payload_limit_exceeded"
}

# Pending limit

If there are more than 5 pending batch requests for a client, a 400 Bad Request will be returned, along with the following response:

{
  "status": "error",
  "error": "pending_limit_exceeded"
}

In this case please wait for at least one of your pending batch requests to finish before making your next batch request.