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

Get a workgroup

GET /v1/workgroups/:id

Returns a workgroup by identifier with all its fields.

Parameters

Parameter Type Required Default Description
Parameterid (path) Typenumber Required★ yes Default— DescriptionWorkgroup identifier. List: GET /v1/workgroups
Parameterinclude (query) Typestring Requiredno Default— DescriptionRelated data: owner. See the "Related data" section below

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/workgroups/85" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/workgroups/85" \
  -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/85', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data } = await res.json()
console.log('Group:', data.name, '— members:', data.membersCount)

JavaScript — OAuth application

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

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

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.id Typenumber DescriptionWorkgroup identifier (read-only)
Fielddata.name Typestring DescriptionName
Fielddata.description Typestring | null DescriptionDescription
Fielddata.active Typeboolean DescriptionWhether the group is active
Fielddata.visible Typeboolean DescriptionWhether the group is visible in shared lists
Fielddata.opened Typeboolean DescriptionWhether it is open for joining without an invitation
Fielddata.ownerId Typenumber DescriptionOwner (responsible person) identifier. List: GET /v1/users
Fielddata.subjectId Typenumber DescriptionSubject identifier
Fielddata.subjectName Typestring DescriptionSubject name (read-only)
Fielddata.membersCount Typenumber DescriptionNumber of members (read-only)
Fielddata.dateCreate Typestring DescriptionCreation date, ISO 8601 (read-only)
Fielddata.dateUpdate Typestring DescriptionLast update date, ISO 8601 (read-only)
Fielddata.dateActivity Typestring DescriptionLast activity date, ISO 8601 (read-only)
Fielddata.archived Typeboolean DescriptionWhether it is archived
Fielddata.isProject Typeboolean DescriptionWhether it is a project with tasks and deadlines
Fielddata.isExtranet Typeboolean DescriptionExtranet group — accessible to external users
Fielddata.keywords Typestring | null DescriptionKeywords
Fielddata.siteId Typestring DescriptionBitrix24 account site identifier, for the main site — s1 (read-only)
Fielddata.imageUrl Typestring | null DescriptionGroup avatar URL (read-only)

To retrieve the related record together with the workgroup — the include parameter in the GET request:

GET /v1/workgroups/79?include=owner

Available include: owner — the profile of the employee who owns the group. The include reads employees, so the key also needs the user scope. The result is in the _included field:

JSON 
{
  "success": true,
  "data": {
    "id": 79,
    "name": "Website redesign",
    "ownerId": 1269,
    "_included": {
      "owner": {
        "id": 1269,
        "name": "John",
        "lastName": "Brown",
        "active": true,
        "timeZone": "Europe/Berlin"
      }
    }
  }
}

More on includes: Related data.

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 85,
    "siteId": "s1",
    "name": "New product development team",
    "description": "Internal infrastructure project",
    "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,
    "imageUrl": null
  }
}

Error response example

404 — a workgroup with this id does not exist:

JSON 
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "workgroup 999999 not found"
  }
}

Errors

HTTP Code Description
HTTP404 CodeENTITY_NOT_FOUND DescriptionA workgroup with the specified id was not found
HTTP400 CodeINVALID_INCLUDE DescriptionAn include the workgroup does not have was requested. The message lists the available ones
HTTP401 CodeMISSING_API_KEY DescriptionX-Api-Key was not passed
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

Full list of common API errors — Errors.

Known specifics

  • A non-numeric id (for example abc) returns 404 ENTITY_NOT_FOUND, not 400 — take this into account when handling validation errors on the client.
  • To change a workgroup's subject, pass a numeric subjectId in PATCH /v1/workgroups/:id. The subjectName field is read-only — an attempt to pass it in the PATCH body returns 400 READONLY_FIELD.

See also