Send a batch of requests with BX24.callBatch

Choose a tool for developing with an AI agent:

use Alaio Vibecode to build an app for Bitrix24 from a task description without knowing any programming language. The agent writes the code and deploys the app to a server, with no manual hosting setup
use the MCP server to develop a REST API integration in your own project. The agent refers to the official REST documentation

void BX24.callBatch(
            Object|Array calls,
            [Function callback[,
            Boolean bHaltOnError = false]]
        );

The BX24.callBatch function sends several Bitrix24 method calls in a single request on behalf of the user who opened the application. A batch is useful when you need to perform a series of calls in a row: for example, to create the required objects during application installation, or to retrieve a user together with their department.

The function returns nothing: the results of all commands are passed to the callback function. If you call BX24.callBatch before BX24.init, the library defers the request until initialization completes.

The function works only inside the frame of an application and only when the BX24.js library is loaded — the Library Overview describes how to load it.

Parameters

Required parameters are marked with *

Name `type`	Description
calls* `object`\|`array`	Batch commands — an array or an object of commands (detailed description). The object keys become the result keys in `callback`. A batch can contain no more than 50 commands: Bitrix24 does not execute the rest. The library does not send an empty batch, and `callback` is not called
callback `function`	Function that receives the command results. Their structure is described in the Response Handling section
bHaltOnError `boolean`	Whether to stop the batch at the first error. Commands after the error are not executed, and their keys are absent from the result. Default is `false`: Bitrix24 executes all commands

Batch Command

A command can be written as an array [method, params] or as an object {method, params}.

Name
type

Description

method*
string

Bitrix24 method name, for example, user.current. The library skips a command without a method name

params
object

Method parameters in the same format as for BX24.callMethod. If the method has no required parameters, you can omit params.

You can refer to the result of a previous command using the $result[command_key][response_field] macro, for example, $result[get_user][UF_DEPARTMENT]

Code Examples

How to Use Examples in Documentation

Retrieve the current user using the user.current method and, in the same batch, their departments using the department.get method. The second command takes the department IDs from the response of the first one using a macro. The UF_DEPARTMENT field is an array, and department.get also accepts a list of IDs in the ID parameter, so it returns the user's departments. Any user can call both methods. The application needs the department scope and one of the scopes for user data: user, user_brief, or user_basic:

BX24.init(() => {
            BX24.callBatch({
                get_user: ['user.current', {}],
                get_department: {
                    method: 'department.get',
                    params: {
                        ID: '$result[get_user][UF_DEPARTMENT]',
                    },
                },
            }, (result) => {
                for (const key of ['get_user', 'get_department'])
                {
                    // with bHaltOnError = true, commands after an error are absent from the result
                    if (!result[key])
                    {
                        console.error(key + ': command was not executed');
                        return;
                    }
        
                    if (result[key].error())
                    {
                        console.error(key + ': ' + result[key].error().toString());
                        return;
                    }
                }
        
                const user = result.get_user.data();
                const departments = result.get_department.data().map((department) => department.NAME);
                console.log(user.NAME + ' ' + user.LAST_NAME + ': ' + departments.join(', ')); // Klaus Weber: Sales Department
            }, true);
        });

Response Handling

Bitrix24 returns a single response to the batch, in which the data, errors, and metadata of each command are grouped by key. The raw response to the batch from the example above, with the user data abbreviated:

{
            "result": {
                "result": {
                    "get_user": {
                        "ID": "10",
                        "ACTIVE": true,
                        "NAME": "Klaus",
                        "LAST_NAME": "Weber",
                        "UF_DEPARTMENT": [1]
                    },
                    "get_department": [
                        {
                            "ID": "1",
                            "NAME": "Sales Department",
                            "SORT": 500
                        }
                    ]
                },
                "result_error": [],
                "result_total": {
                    "get_department": 1
                },
                "result_next": [],
                "result_time": {
                    "get_user": {
                        "start": 1790289763,
                        "finish": 1790289763.9619,
                        "duration": 0.9619,
                        "processing": 0,
                        "date_start": "2026-09-24T22:42:43+00:00",
                        "date_finish": "2026-09-24T22:42:43+00:00"
                    },
                    "get_department": {
                        "start": 1790289763,
                        "finish": 1790289763.9637,
                        "duration": 0.9637,
                        "processing": 0,
                        "date_start": "2026-09-24T22:42:43+00:00",
                        "date_finish": "2026-09-24T22:42:43+00:00"
                    }
                }
            },
            "time": {
                "start": 1790289763,
                "finish": 1790289763.9651,
                "duration": 0.9651,
                "processing": 0,
                "date_start": "2026-09-24T22:42:43+00:00",
                "date_finish": "2026-09-24T22:42:43+00:00"
            }
        }

The library splits this response by command. If calls is an object, callback receives results with the same keys; if it is an array, callback receives an array of results in the same order. Each result is an ajaxResult object. Its methods read the fields of the raw response by the command key:

Method	Raw response field	What it returns
`data()`	`result.result[key]`	The command data. For a command with an error, an empty object `{}`
`error()`	`result.result_error[key]`	An error object, or `undefined` if there is no error
`total()`	`result.result_total[key]`	The total number of records in the list, or `NaN` if the method did not return it
`more()`	`result.result_next[key]`	`true` if the list has a next page, otherwise `false`
`next(cb)`	`result.result_next[key]`	Requests the next page. It returns `false` if there are no more pages, and `undefined` if the request has been sent

For example, result.get_department.data() returns the array from the result.result.get_department field. All fields of the raw response are described on the page of the batch method.

A command result differs from a BX24.callMethod result:

error_description() always returns undefined. The error message is in result[key].error().ex.error_description
the answer property does not contain the request execution time
next() requests the next page with a separate method call, outside the batch. Pass a separate handler to next(): without it, the page is passed to the batch callback as a single result rather than as an object with keys
if the command parameters contain a $result macro, next() sends it as is: Bitrix24 substitutes macros only inside a batch. For such a command, request the next page with a new batch of one command, with resolved parameter values and the start parameter. This does not work with BX24.callMethod: the library removes a non-zero start from params

Error Handling

An error is returned for each command separately. If bHaltOnError is not enabled, the remaining commands of the batch are executed. The result[key].error() method returns the same error object as BX24.callMethod. The HTTP status in it is the status of the entire batch, so for a command error it is usually 200:

{
            "status": 200,
            "ex": {
                "error": "ERROR_METHOD_NOT_FOUND",
                "error_description": "Method not found!"
            }
        }

In the raw batch response, this error is in the result.result_error field under the command key — see the example on the page of the batch method.

If bHaltOnError is enabled, the keys of commands after the error are absent from the result. Check that the key exists before calling error(): otherwise, the handler stops with a JavaScript error.

Name `type`	Description
error `string`	String error code. It consists of digits, Latin letters, and underscores. It may arrive empty — in that case only `error_description` shows the reason
error_description `string`	Error message for the developer. Do not show it to the end user without processing

Possible Error Codes

Command error codes depend on the called method and are described on its page. Errors of the batch itself:

Status	Code	Description	Meaning
`200`	`ERROR_BATCH_LENGTH_EXCEEDED`	Max batch length exceeded	The batch contains more than 50 commands. If `bHaltOnError` is not enabled, every command beyond the limit receives this error; otherwise, only the first of them does
`200`	`ERROR_BATCH_METHOD_NOT_ALLOWED`	Method is not allowed for batch usage	The method cannot be called inside a batch, for example, a nested batch

The following are not passed to callback:

the expired_token error. The library refreshes the authorization itself and retries the batch, and callback receives the result of the retry
any other error that Bitrix24 returns for the entire batch rather than for an individual command. The library stops with a JavaScript error while parsing the response
a response with a 5xx status, a network failure, and a response that could not be parsed as JSON. The library throws a Query error! exception from the asynchronous request handler, so a try/catch around the call does not catch it

Statuses and System Error Codes

HTTP Status: 4xx, 5xx

The errors described below are returned by the REST API itself, not by the logic of a specific method. They can arrive in response to any method.

Status	Code Error Message	Description
`500`	`INTERNAL_SERVER_ERROR` Internal server error	An internal server error has occurred. Retry the call, and if the error persists, contact the server administrator or Bitrix24 technical support
`500`	`ERROR_UNEXPECTED_ANSWER` Server returned an unexpected response	The server returned an unexpected response. Retry the call, and if the error persists, contact the server administrator or Bitrix24 technical support
`503`	`QUERY_LIMIT_EXCEEDED` Too many requests	The request intensity limit has been exceeded
`429`	`OPERATION_TIME_LIMIT` Method is blocked due to operation time limit	The method is blocked because the request resource intensity limit has been exceeded. The block is lifted automatically once the accumulated execution time of the method no longer exceeds the limit
`401`	`NO_AUTH_FOUND` Wrong authorization data	The request contains no authorization data: neither an access token nor a webhook code was passed
`401`	`INVALID_REQUEST` Https required	Methods are called over the HTTPS protocol only
`401`	`OVERLOAD_LIMIT` REST API is blocked due to overload	The REST API is blocked due to overload. This is a manual individual block. To have it lifted, contact Bitrix24 technical support
`401`	`ACCESS_DENIED` REST is available only on commercial plans	REST API access is not active for this account. In Bitrix24 Cloud, check the current plan or trial status: Vibe+ plans include REST API access, while Essentials plans do not. A webhook receives a different error message — `REST is available only by subscription`
`401`	`INVALID_CREDENTIALS` Invalid request credentials	No active webhook with the specified user identifier and secret code was found
`404`	`ERROR_METHOD_NOT_FOUND` Method not found!	No method with this name was found. The name is misspelled, the method does not exist in the REST API, or it is unavailable without the required scope
`401`	`insufficient_scope` The request requires higher privileges than provided by the webhook token	The request requires broader permissions than the token has: for a webhook these are the permissions granted to it, for an application it is the scope. For an application, the error message ends with `provided by the access token`
`401`	`expired_token` The access token provided has expired	The access token has expired
`401`	`user_access_error` The user does not have access to the application	The application is installed, but the Bitrix24 administrator has granted access to it only to specific users
`403`	`PORTAL_DELETED` Portal was deleted	The public part of the site is closed. To open it on an on-premise installation, disable the "Temporary closure of the public part of the site" option. Path to the setting: Desktop > Settings > Product Settings > Module Settings > Main Module > Temporary closure of the public part of the site

Continue Learning

Was the article helpful?

Call Method

Send a batch of requests with BX24.callBatch

ParametersParameters

Batch CommandBatch Command

Code ExamplesCode Examples

Response HandlingResponse Handling

Error HandlingError Handling

Possible Error CodesPossible Error Codes

Statuses and System Error CodesStatuses and System Error Codes

Continue LearningContinue Learning