For AI agents: markdown of this page — /docs-content-en/entities/workgroups/list.md documentation index — /llms.txt

List workgroups

GET /v1/workgroups

Returns a list of workgroups in your Bitrix24 account with support for filtering, sorting and automatic pagination.

Parameters

Parameter Type Required Default Description
Parameterfilter (query) Typeobject Requiredno Default— DescriptionFiltering by fields from GET /v1/workgroups/fields.
Filtering syntax. Example: ?filter[archived]=N
Parameterselect (query) Typearray Requiredno Default— DescriptionList of fields in the response. Field names come from GET /v1/workgroups/fields.
Parametersort (query) Typestring Requiredno Default— DescriptionSorting: ?sort=dateCreate — ascending, ?sort=-dateCreate — descending. The forms ?sort[dateCreate]=DESC and ?order[dateCreate]=desc are accepted too
Parameterlimit (query) Typenumber Requiredno Default50 DescriptionMaximum records in the response. Up to 5000 allowed.
Parameteroffset (query) Typenumber Requiredno Default0 DescriptionOffset from the start of the selection.
Parameterinclude (query) Typestring Requiredno Default— DescriptionRelated data: owner — the group owner. See the "Related data" section below
ParameterwithTotal (query) Typestring Requiredno Default— DescriptionThe values true and false are recognized. For workgroups, the parameter does not affect the response: meta.total is returned even with withTotal=false

For limit > 50, Vibecode automatically paginates the request on the server side. The maximum is 5000 records per call. If more records match the filter, meta.hasMore is true.

Get projects only

A single collection stores both workgroups and projects. The isProject field distinguishes them: true — a project, false — an ordinary workgroup. To select projects, pass filter[isProject]=Y.

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/workgroups?limit=3" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/workgroups?limit=3" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/workgroups?limit=3', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data, meta } = await res.json()
console.log(`Found ${meta.total} workgroups`)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/workgroups?limit=3', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data, meta } = await res.json()

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typearray DescriptionArray of workgroups (all fields — see Workgroup fields)
Fieldmeta.total Typenumber DescriptionTotal number of records matching the filter
Fieldmeta.hasMore Typeboolean DescriptionWhether there are more records beyond limit
Fieldmeta.includeSkipped Typeboolean Descriptiontrue when the response holds more than 200 records and the relations from include were not loaded. Reduce limit. With 200 records or fewer the key is absent

To get the owner of each group together with the list, pass the include parameter in the GET request:

GET /v1/workgroups?limit=2&include=owner

Available include value:

Name By field Key in _included Result
Nameowner By fieldownerId — the group owner Key in _includedowner ResultEmployee card

The employee card is the same as in the GET /v1/users/:id response. Loading this relation requires the user scope in addition to sonet_group. The result is in the _included field of each data element:

JSON 
{
  "success": true,
  "data": [
    {
      "id": 79,
      "name": "Marketing 2026",
      "ownerId": 1269,
      "isProject": true,
      "_included": {
        "owner": { "id": 1269, "name": "John", "lastName": "Smith", "email": "john.smith@example.com", "active": true }
      }
    }
  ],
  "meta": { "total": 29, "hasMore": true }
}

Only the main group and employee fields are shown. For the full list of employee fields, see Employee fields.

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "id": 85,
      "siteId": "s1",
      "name": "Marketing 2026",
      "description": null,
      "dateCreate": "2026-03-20T06:45:10.000Z",
      "dateUpdate": "2026-03-20T06:45:10.000Z",
      "active": true,
      "visible": true,
      "opened": false,
      "archived": false,
      "subjectId": 1,
      "ownerId": 1271,
      "keywords": null,
      "membersCount": 2,
      "dateActivity": "2026-03-20T06:45:10.000Z",
      "subjectName": "Workgroups",
      "isProject": true,
      "isExtranet": false
    },
    {
      "id": 83,
      "siteId": "s1",
      "name": "New product development team",
      "description": null,
      "dateCreate": "2026-03-20T06:41:07.000Z",
      "dateUpdate": "2026-03-20T06:41:07.000Z",
      "active": true,
      "visible": true,
      "opened": false,
      "archived": false,
      "subjectId": 1,
      "ownerId": 1269,
      "keywords": null,
      "membersCount": 1,
      "dateActivity": "2026-03-20T06:41:07.000Z",
      "subjectName": "Workgroups",
      "isProject": true,
      "imageUrl": "https://cdn.bitrix24.com/example/disk/avatar.jpg",
      "isExtranet": false
    },
    {
      "id": 81,
      "siteId": "s1",
      "name": "Regional office launch",
      "description": null,
      "dateCreate": "2026-03-20T06:29:07.000Z",
      "dateUpdate": "2026-03-20T06:29:07.000Z",
      "active": true,
      "visible": true,
      "opened": false,
      "archived": false,
      "subjectId": 1,
      "ownerId": 1271,
      "keywords": null,
      "membersCount": 1,
      "dateActivity": "2026-03-20T06:29:07.000Z",
      "subjectName": "Workgroups",
      "isProject": true,
      "isExtranet": false
    }
  ],
  "meta": {
    "total": 33,
    "hasMore": true
  }
}

Error response example

401 — no authorization key:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key required. Pass via X-Api-Key header."
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_INCLUDE DescriptionAn unknown name was passed in include. The message lists the available ones: Unknown include 'bad'. Available: owner
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing
HTTP401 CodeINVALID_API_KEY DescriptionThe key is not recognized — no such key exists on the platform
HTTP403 CodeSCOPE_DENIED DescriptionThe key is missing the sonet_group scope
HTTP403 CodeSCOPE_DENIED Descriptioninclude=owner was passed, but the key lacks the user scope
HTTP429 CodeRATE_LIMITED DescriptionRate limit exceeded: 300 requests per minute per portal. All API keys of the portal share one limit. The exact limit is returned in the x-ratelimit-limit header. Retry after the delay in the Retry-After header

For the full list of common API errors, see Errors.

Known specifics

Boolean fields in the filter accept Y / N. In the response, the same fields come back as true / false, but when filtering use filter[active]=Y / filter[archived]=N. The values true / false in the filter will not produce matches and will not raise an error.

A % prefix in the field name enables substring search. ?filter[%name]=Marketing will find all groups whose name contains "Marketing". Without the prefix the filter requires an exact match.

limit = 0 is not a page size — the parameter is dropped, the default page size (50) applies, and the response carries a LIMIT_ZERO_IGNORED warning in meta.warnings. To read the whole collection, pass an explicit limit (up to 5000). For an empty selection, use a filter that is guaranteed to find nothing.

See also