Get a List of Workgroups socialnetwork.api.workgroup.list

If you are developing integrations for Bitrix24 using AI tools (Codex, Claude Code, Cursor), connect to the MCP server so that the assistant can utilize the official REST documentation.

Scope: socialnetwork

Who can execute the method: any user

The method socialnetwork.api.workgroup.list returns a list of workgroups, projects, scrums, and collaborations based on the current user's permissions.

Method Parameters

Required parameters are marked with *

Name `type`	Description
filter `object`	An object for filtering in the format `{"field_1": "value_1", ... "field_N": "value_N"}`. See below for the list of available fields for filtering. An additional prefix can be specified for the key to clarify the filter's behavior. Possible prefix values: `>=` — greater than or equal to `>` — greater than `<=` — less than or equal to `<` — less than `%` — LIKE, substring search. The `%` symbol in the filter value does not need to be passed `=%` — LIKE, substring search. The `%` symbol needs to be passed in the value `%=` — LIKE (similar to `=%`) `!%` — NOT LIKE, substring search. The `%` symbol in the filter value does not need to be passed `!=%` — NOT LIKE, substring search. The `%` symbol needs to be passed in the value `!%=` — NOT LIKE (similar to `!=%`) `=` — equal, exact match (used by default) `!=` — not equal `!` — not equal If `IS_ADMIN = Y` is not passed in `params`, the method automatically adds a check for the current user's permissions `CHECK_PERMISSIONS`. The method also always adds a filter by site: for extranet users, the extranet site is used for others — the site from `params[siteId]` or the current account site
select `array`	An array containing the list of fields to select. See below for the list of available fields for selection. If the parameter is not passed or is empty, only `ID` is selected.
order `object`	A sorting object in the format `{"field_1": "order_1", ..., "field_N": "order_N"}`. Possible values for `field` correspond to the fields from the list of available fields for filtering. Possible values for `order`: `ASC` — ascending order `DESC` — descending order
params `object`	Additional request parameters
start `integer`	Pagination parameter. The page size for results is 50 records. To get the second page, pass `50`; for the third — `100`, and so on. Formula: `start = (N - 1) * 50`, where `N` is the page number. If `-1` is passed, the response will not include the `total` field.

Available Fields for Filtering

Name `type`	Description
ID `integer`	Group identifier
NAME `string`	Group name
OWNER_ID `integer`	Owner identifier
ACTIVE `string`	Group activity status: `Y` or `N`
VISIBLE `string`	Group visibility in the general list: `Y` or `N`
OPENED `string`	Is the group open for free membership: `Y` or `N`
CLOSED `string`	Is the group archived: `Y` or `N`
PROJECT `string`	Object type: `Y` — project, `N` — group
SUBJECT_ID `integer`	Group subject identifier
SITE_ID `string`	Group site identifier
DATE_CREATE `datetime`	Group creation date
DATE_UPDATE `datetime`	Group modification date
DATE_ACTIVITY `datetime`	Last activity date

Available Fields for Selection

Name `type`	Description
ID `integer`	Group identifier
ACTIVE `string`	Group activity status
SUBJECT_ID `integer`	Group subject identifier
NAME `string`	Group name
DESCRIPTION `string`	Group description
KEYWORDS `string`	Group keywords
CLOSED `string`	Archive group status
VISIBLE `string`	Group visibility status
OPENED `string`	Open group status
PROJECT `string`	Project status
LANDING `string`	Group for publication status
DATE_CREATE `datetime`	Creation date
DATE_UPDATE `datetime`	Modification date
DATE_ACTIVITY `datetime`	Last activity date
IMAGE_ID `integer`	User avatar identifier
AVATAR_TYPE `string`	System avatar type
OWNER_ID `integer`	Owner identifier
NUMBER_OF_MEMBERS `integer`	Number of participants
NUMBER_OF_MODERATORS `integer`	Number of moderators
INITIATE_PERMS `string`	Permissions to invite participants
PROJECT_DATE_START `datetime`	Project start date
PROJECT_DATE_FINISH `datetime`	Project end date
SCRUM_OWNER_ID `integer`	Scrum owner identifier
SCRUM_MASTER_ID `integer`	Scrum master identifier
SCRUM_SPRINT_DURATION `integer`	Sprint duration in seconds
SCRUM_TASK_RESPONSIBLE `string`	Default executor in scrum
TYPE `string`	Group type: `group`, `project`, `scrum`, `collab`
AVATAR `string`	Avatar URL

Parameter params

Name `type`	Description
IS_ADMIN `string`	Disable permission check. Possible values: `Y` — disable permission check if the current user is an administrator If `Y` is passed by a non-administrator, the value is ignored.
siteId `string`	Identifier of the site to be used in the automatic filter `SITE_ID` for regular users. For extranet users, this value is ignored: the method always uses the extranet site.
mode `string`	Response mode. Supported value: `mobile` — adds the `additionalData` field to each list item The `additionalData` field has the structure: `role` — the current user's role in the group `initiatedByType` — who initiated the user's connection to the group: `U` — the user themselves (e.g., sent a request to join) `G` — the group (e.g., the user was invited) `features` — list of available group tools (returned if `features`/`mandatoryFeatures` are passed)
features `array`	List of group tool codes to consider when forming `additionalData` in `mobile` mode
mandatoryFeatures `array`	List of tool codes that should always be included in `additionalData` in `mobile` mode
shouldSelectDialogId `string`	Whether to add a field with the chat identifier `dialogId` to the list item. Possible values: `Y` — add `dialogId` `N` — do not add `dialogId` Default — `N`

Code Examples

How to Use Examples in Documentation

cURL (Webhook)

cURL (OAuth)

PHP

BX24.js

PHP CRest

curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"filter":{"ACTIVE":"Y","CLOSED":"N","%NAME":"group"},"select":["ID","NAME","TYPE","AVATAR"],"order":{"ID":"DESC"},"params":{"mode":"mobile","shouldSelectDialogId":"Y"}}' \
        https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/socialnetwork.api.workgroup.list

curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"filter":{"ACTIVE":"Y","CLOSED":"N","%NAME":"group"},"select":["ID","NAME","TYPE","AVATAR"],"order":{"ID":"DESC"},"params":{"mode":"mobile","shouldSelectDialogId":"Y"},"auth":"**put_access_token_here**"}' \
        https://**put_your_bitrix24_address**/rest/socialnetwork.api.workgroup.list

// callListMethod: Retrieves all data at once. Use only for small selections (< 1000 items) due to high memory load.
        try {
            const response = await $b24.callListMethod(
                'socialnetwork.api.workgroup.list',
                {
                    filter: { ACTIVE: 'Y', CLOSED: 'N', '%NAME': 'group' },
                    select: ['ID', 'NAME', 'TYPE', 'AVATAR'],
                    order: { ID: 'DESC' },
                    params: { mode: 'mobile', shouldSelectDialogId: 'Y' }
                },
                (progress) => { console.log('Progress:', progress) }
            );
        
            const items = response.getData() || [];
            for (const entity of items) { console.log('Entity:', entity) }
        } catch (error) {
            console.error('Request failed', error);
        }
        
        // fetchListMethod: Retrieves data in parts using an iterator. Use for large volumes of data for efficient memory consumption.
        try {
            const generator = $b24.fetchListMethod(
                'socialnetwork.api.workgroup.list',
                {
                    filter: { ACTIVE: 'Y', CLOSED: 'N', '%NAME': 'group' },
                    select: ['ID', 'NAME', 'TYPE'],
                    order: { ID: 'DESC' }
                },
                'ID'
            );
            for await (const page of generator) {
                for (const entity of page) { console.log('Entity:', entity) }
            }
        } catch (error) {
            console.error('Request failed', error);
        }
        
        // callMethod: Manual control of pagination through the start parameter.
        try {
            const response = await $b24.callMethod(
                'socialnetwork.api.workgroup.list',
                {
                    filter: { ACTIVE: 'Y', CLOSED: 'N', '%NAME': 'group' },
                    select: ['ID', 'NAME', 'TYPE'],
                    order: { ID: 'DESC' }
                },
                0
            );
            const result = response.getData().result.workgroups || [];
            for (const entity of result) { console.log('Entity:', entity) }
        } catch (error) {
            console.error('Request failed', error);
        }

try {
            $response = $b24Service
                ->core
                ->call(
                    'socialnetwork.api.workgroup.list',
                    [
                        'filter' => ['ACTIVE' => 'Y', 'CLOSED' => 'N', '%NAME' => 'group'],
                        'select' => ['ID', 'NAME', 'TYPE', 'AVATAR'],
                        'order' => ['ID' => 'DESC'],
                        'params' => [
                            'mode' => 'mobile',
                            'shouldSelectDialogId' => 'Y',
                        ],
                    ]
                );
        
            print_r($response->getResponseData()->getResult());
        } catch (\Throwable $exception) {
            echo $exception->getMessage();
        }

BX24.callMethod(
            'socialnetwork.api.workgroup.list',
            {
                filter: { ACTIVE: 'Y', CLOSED: 'N', '%NAME': 'group' },
                select: ['ID', 'NAME', 'TYPE', 'AVATAR'],
                order: { ID: 'DESC' },
                params: { mode: 'mobile', shouldSelectDialogId: 'Y' }
            },
            function(result) {
                if (result.error()) {
                    console.error(result.error());
                } else {
                    console.log(result.data());
                }
            }
        );

require_once('crest.php');
        
        $result = CRest::call(
            'socialnetwork.api.workgroup.list',
            [
                'filter' => ['ACTIVE' => 'Y', 'CLOSED' => 'N', '%NAME' => 'group'],
                'select' => ['ID', 'NAME', 'TYPE', 'AVATAR'],
                'order' => ['ID' => 'DESC'],
                'params' => [
                    'mode' => 'mobile',
                    'shouldSelectDialogId' => 'Y',
                ],
            ]
        );
        
        print_r($result);

Response Handling

HTTP Status: 200

{
            "result": {
                "workgroups": [
                        {
                    "id": "5",
                    "name": "Open group for everyone",
                    "type": "group",
                    "imageId": "5",
                    "avatarType": null,
                    "avatar": "https://test.bitrix24.com/b13743910/resize_cache/5/7acf4caaf5d8/socialnetwork/8d6/8d2c04ece929572/3.png",
                    "additionalData": {
                    "role": "",
                    "initiatedByType": ""
                    },
                    "dialogId": ""
                },
                {
                    "id": "1",
                    "name": "Closed visible group",
                    "type": "group",
                    "imageId": "1",
                    "avatarType": null,
                    "avatar": "",
                    "additionalData": {
                    "role": "",
                    "initiatedByType": ""
                    },
                    "dialogId": "chat177"
                }
                ]
            },
            "total": 2,
            "time": {
                "start": 1774357689,
                "finish": 1774357689.398272,
                "duration": 0.3982720375061035,
                "processing": 0,
                "date_start": "2026-03-24T16:08:09+02:00",
                "date_finish": "2026-03-24T16:08:09+02:00",
                "operating_reset_at": 1774358289,
                "operating": 0.12220001220703125
            }
        }

Returned Data

Name `type`	Description
result `object`	Root object of the response
workgroups `object[]`	List of workgroups. The structure of the object depends on the fields passed in `select` and the parameters in `params`. If no groups are found by the filter, `workgroups` will return an empty array.
next `integer`	Offset for the next page. The field is returned if there are more records.
total `integer`	Total number of records. The field is not returned if the request is executed with `start = -1`.
time `time`	Information about the execution time of the request.

Error Handling

Statuses and System Error Codes

HTTP Status: 20x, 40x, 50x

The errors described below may occur when calling any method.

Status	Code Error Message	Description
`500`	`INTERNAL_SERVER_ERROR` Internal server error	An internal server error has occurred. Please contact the server administrator or Bitrix24 technical support
`500`	`ERROR_UNEXPECTED_ANSWER` Server returned an unexpected response	An internal server error has occurred. Please contact the server administrator or Bitrix24 technical support
`503`	`QUERY_LIMIT_EXCEEDED` Too many requests	The request intensity limit has been exceeded
`405`	`ERROR_BATCH_METHOD_NOT_ALLOWED` Method is not allowed for batch usage	The current method is not permitted for calls using batch
`400`	`ERROR_BATCH_LENGTH_EXCEEDED` Max batch length exceeded	The maximum length of parameters passed to the batch method has been exceeded
`401`	`NO_AUTH_FOUND` Wrong authorization data	Invalid access token or webhook code
`400`	`INVALID_REQUEST` Https required	The HTTPS protocol is required for method calls
`503`	`OVERLOAD_LIMIT` REST API is blocked due to overload	The REST API is blocked due to overload. This is a manual individual block; please contact Bitrix24 technical support to lift it
`403`	`ACCESS_DENIED` REST API is available only on commercial plans	The REST API is only available on commercial plans
`403`	`INVALID_CREDENTIALS` Invalid request credentials	The user associated with the access token or webhook used to call the method lacks the necessary permissions
`404`	`ERROR_MANIFEST_IS_NOT_AVAILABLE` Manifest is not available	The manifest is not available
`403`	`insufficient_scope` The request requires higher privileges than provided by the webhook token	The request requires higher privileges than those provided by the webhook token
`401`	`expired_token` The access token provided has expired	The provided access token has expired
`403`	`user_access_error` The user does not have access to the application	The user does not have access to the application. This means that the application is installed, but the portal administrator has restricted access to this application to specific users only
`500`	`PORTAL_DELETED` Portal was deleted	The public part of the site is closed. To open the public part of the site 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

Retrieve Workgroup Data

Get List of Groups and Projects

Get a List of Workgroups socialnetwork.api.workgroup.list

Method ParametersMethod Parameters

Available Fields for FilteringAvailable Fields for Filtering

Available Fields for SelectionAvailable Fields for Selection

Parameter paramsParameter params

Code ExamplesCode Examples

Response HandlingResponse Handling

Returned DataReturned Data

Error HandlingError Handling

Statuses and System Error CodesStatuses and System Error Codes

Continue LearningContinue Learning