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 Req. Default Description
id (path) number ★ yes — Workgroup identifier. List: GET /v1/workgroups
include (query) string no — Related 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
success boolean Always true on success
data.id number Workgroup identifier (read-only)
data.name string Name
data.description string | null Description
data.active boolean Whether the group is active
data.visible boolean Whether the group is visible in shared lists
data.opened boolean Whether it is open for joining without an invitation
data.ownerId number Owner (responsible person) identifier. List: GET /v1/users
data.subjectId number Subject identifier
data.subjectName string Subject name (read-only)
data.membersCount number Number of members (read-only)
data.dateCreate string Creation date, ISO 8601 (read-only)
data.dateUpdate string Last update date, ISO 8601 (read-only)
data.dateActivity string Last activity date, ISO 8601 (read-only)
data.archived boolean Whether it is archived
data.isProject boolean Whether it is a project with tasks and deadlines
data.isExtranet boolean Extranet group — accessible to external users
data.keywords string | null Keywords
data.siteId string Bitrix24 account site identifier, for the main site — s1 (read-only)
data.imageUrl string | null Group 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
404 ENTITY_NOT_FOUND A workgroup with the specified id was not found
400 INVALID_INCLUDE An include the workgroup does not have was requested. The message lists the available ones
401 MISSING_API_KEY X-Api-Key was not passed
401 INVALID_API_KEY An invalid key was passed
403 SCOPE_DENIED The 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