How to Execute Batch Requests in REST 3.0

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

Scope: basic

Who can execute the method: any user

This method belongs to REST 3.0. The call specifics and response format of the new API version are described in the REST 3.0 overview.

The REST 3.0 batch method executes multiple requests in a single API call. You can pass the result of a previous subrequest to the parameters of the next one.

Method endpoint:

POST https://{installation_address}/rest/api/{user_id}/{webhook_token}/batch

Pass the request body in JSON format as an array of subrequest objects.

When to Use batch

The method supports two scenarios:

execute multiple independent methods in a single server call
pass the result of one subrequest to the parameters of the next one

Method Parameters

The method accepts a JSON array of subrequests in the request body. Each array element is an object that describes one call.

Batch Array Element

Required parameters are marked with *

Name `type`	Description
method* `string`	Name of the method to call
query* `object`	Parameters of the method to call. If the method has no parameters, pass an empty object `{}`
as `string`	Unique name of the subrequest result. Use this name to reference the result in subsequent subrequests. If `as` is not specified, reference the result by the subrequest index. Indexing starts at zero. If two subrequests have the same name, batch returns the `BITRIX_REST_V3_EXCEPTION_INVALIDSELECTEXCEPTION` error

Passing a Single Value

To pass a value from a previous subrequest result, use an object with the $ref key:

{"$ref": "first_task.id"}

The path consists of the subrequest identifier and the dot-separated path to the field. The identifier can be an as value or a subrequest index, such as 1.id.

Passing an Array of Values

To collect the values of one field from all result items, use $refArray:

{"$refArray": "tasks_list.id"}

In this example, the API takes the tasks_list subrequest result, extracts the id field from each item, and passes the resulting array to the next request.

Code Examples

How to Use Examples in Documentation

The new API call differs by adding the /api/ segment to the request URL:

https://{installation_address}/rest/api/{user_id}/{webhook_token}/batch

Send a direct HTTP request to call batch 3.0.

Independent Calls

If the subrequest results are not related, pass them in a single array without $ref and $refArray references:

cURL (Webhook)

curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '[
            {"method":"tasks.task.get","query":{"id":101,"select":["id","title"]}},
            {"method":"tasks.task.get","query":{"id":102,"select":["id","title"]}}
        ]' \
        https://**put_your_bitrix24_address**/rest/api/**put_your_user_id_here**/**put_your_webhook_here**/batch

Each result in the response corresponds to the subrequest with the same index.

Sequential Execution

The subrequests are executed in the following order:

tasks.task.get retrieves a task and stores the result under the name first_task
The second tasks.task.get call retrieves another task. The subrequest has no name, so its result is referenced by the index 1
tasks.task.update retrieves the task ID from first_task through $ref and updates its title
tasks.task.list retrieves tasks by their IDs and stores the list under the name tasks_list
The second tasks.task.list call retrieves all IDs from tasks_list through $refArray

cURL (Webhook)

curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '[
            {"method":"tasks.task.get","query":{"id":101,"select":["id","title"]},"as":"first_task"},
            {"method":"tasks.task.get","query":{"id":102,"select":["id","title"]}},
            {"method":"tasks.task.update","query":{"id":{"$ref":"first_task.id"},"fields":{"title":"Updated task"}}},
            {"method":"tasks.task.list","query":{"select":["id","title"],"filter":["id",[101,{"$ref":"first_task.id"},{"$ref":"1.id"}]]},"as":"tasks_list"},
            {"method":"tasks.task.list","query":{"select":["id","title"],"filter":["id",{"$refArray":"tasks_list.id"}]}}
        ]' \
        https://**put_your_bitrix24_address**/rest/api/**put_your_user_id_here**/**put_your_webhook_here**/batch

REST 3.0 does not support the format with a cmd object and strings such as method?param=value. Pass subrequests as a JSON array of objects.

Response Handling

HTTP status of a successful response: 200.

{
            "result": [
                {
                    "item": {
                        "id": 101,
                        "title": "First task"
                    }
                },
                {
                    "item": {
                        "id": 102,
                        "title": "Second task"
                    }
                },
                {
                    "result": true
                },
                {
                    "items": [
                        {
                            "id": 101,
                            "title": "Updated task"
                        },
                        {
                            "id": 102,
                            "title": "Second task"
                        }
                    ]
                },
                {
                    "items": [
                        {
                            "id": 101,
                            "title": "Updated task"
                        },
                        {
                            "id": 102,
                            "title": "Second task"
                        }
                    ]
                }
            ],
            "time": {
                "start": 1750096028,
                "finish": 1750096028.292702,
                "duration": 0.29270195960998535,
                "processing": 0,
                "date_start": "2025-06-16T17:47:08+00:00",
                "date_finish": "2025-06-16T17:47:08+00:00"
            }
        }

Returned Data

Name `type`	Description
result `array`	Array of subrequest results in execution order
result[n] `object`	Result of the subrequest with the index `n`. Indexing starts at zero. Method data is located in `item`, `items`, or `result`, depending on the called method
result[].item `object`	Result of a method that returns one object
result[].items `array`	Result of a method that returns a list of objects
result[].result `boolean`	Operation result when the method returns a success indicator
time `time`	Information about the batch execution time

If an error occurs in the batch request itself or in a nested call, batch returns an error object at the top level and does not return an array of successful results. Check the HTTP status and error code. The general error format is described in the REST 3.0 overview.

Example of an error when referencing a nonexistent path in $ref:

HTTP status: 400

{
            "error": {
                "code": "BITRIX_REST_V3_EXCEPTION_INVALIDSELECTEXCEPTION",
                "message": "Unable to parse select expression `Path 'first_task.item.id' not found in context`"
            }
        }

Name `type`	Description
error.code `string`	String error code. Use it to identify the type of exception
error.message `string`	Text description of the error
error.validation `array`	Array with error details. Present only in data validation errors `BITRIX_REST_V3_EXCEPTION_VALIDATION_REQUESTVALIDATIONEXCEPTION`
error.validation[].field `string`	Name of the field where the validation error occurred
error.validation[].message `string`	Description of the error related to the specified field

Possible Error Codes

Code	HTTP Status	Cause	What to Check
`BITRIX_REST_V3_EXCEPTION_INVALIDJSONEXCEPTION`	400	The request body is not valid JSON	Check brackets, quotation marks, and Content-Type `application/json`
`BITRIX_REST_V3_EXCEPTION_VALIDATION_REQUESTVALIDATIONEXCEPTION`	400	The nested method parameters failed validation	Check `query` and the requirements on the nested method page
`BITRIX_REST_V3_EXCEPTION_INVALIDSELECTEXCEPTION`	400	The `$ref` reference or `select` expression could not be parsed, or an `as` name is duplicated	Check the subrequest name, field path, and uniqueness of `as`
`BITRIX_REST_V3_EXCEPTION_ENTITYNOTFOUNDEXCEPTION`	400	The nested method did not find an object with the specified ID	Check the object ID
`BITRIX_REST_V3_EXCEPTION_ACCESSDENIEDEXCEPTION`	403	The user does not have access to the object	Check the user permissions
`BITRIX_REST_V3_EXCEPTION_INSUFFICIENTSCOPEEXCEPTION`	403	The webhook or application does not have the required scope	Add the scope required by the nested method
`BITRIX_REST_V3_EXCEPTION_METHODNOTFOUNDEXCEPTION`	400	The batch specifies a method that does not exist in the API	Check the nested method name and version

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

Limitations

Subrequests are executed sequentially only
A nested batch call is not supported

Continue Learning

Was the article helpful?

How to Execute a Batch of Requests

Features of REST Calls When Changing the Bitrix24 Address

How to Execute Batch Requests in REST 3.0

When to Use batchWhen to Use batch

Method ParametersMethod Parameters

Batch Array ElementBatch Array Element

Passing a Single ValuePassing a Single Value

Passing an Array of ValuesPassing an Array of Values

Code ExamplesCode Examples

Independent CallsIndependent Calls

Sequential ExecutionSequential Execution

Response HandlingResponse Handling

Returned DataReturned Data

Error HandlingError Handling

Possible Error CodesPossible Error Codes

Statuses and System Error CodesStatuses and System Error Codes

LimitationsLimitations

Continue LearningContinue Learning