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

Get task

GET /v1/tasks/:id

Returns a single task with all fields. In addition to the list fields, the response includes embedded objects for the creator and the responsible person, the checklist, the allowed actions, and extended information about participants and observers.

Parameters

Parameter Type Required Description
Parameterid (path) Typenumber Requiredyes DescriptionTask ID

Examples

curl — personal key

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

curl — OAuth application

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

const { success, data } = await res.json()
console.log(data.title, '— status:', data.status)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/tasks/289', {
  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 Typeobject DescriptionThe task object. Base fields — see Task fields. Additional blocks are described below

Additional blocks in the single-task response:

Field Type Description
Fielddata.creator Typeobject DescriptionCreator: { id, name, link, icon, workPosition }
Fielddata.responsible Typeobject DescriptionResponsible person: same format as creator
Fielddata.accomplicesData Typeobject[] DescriptionDetails about participants (same format as creator)
Fielddata.auditorsData Typeobject[] DescriptionDetails about observers (same format as creator)
Fielddata.action Typeobject DescriptionMap of allowed actions (boolean): complete, start, pause, delegate, remove, edit, defer, changeDeadline, checklistAddItems, and others
Fielddata.checklist Typearray DescriptionChecklist items (an empty array if the task has no checklist)
Fielddata.checkListTree Typeobject DescriptionChecklist tree with metadata
Fielddata.newCommentsCount Typenumber DescriptionNumber of unread comments

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 289,
    "title": "Prepare the quarterly report",
    "description": "",
    "status": 2,
    "priority": 1,
    "groupId": 0,
    "responsibleId": 79,
    "createdBy": 99,
    "createdDate": "2026-05-12T09:11:18.000Z",
    "changedDate": "2026-05-12T09:11:18.000Z",
    "deadline": "2026-05-19T18:00:00.000Z",
    "accomplices": [],
    "auditors": [],
    "checklist": [],
    "creator": {
      "id": "99",
      "name": "Jane Doe",
      "link": "/company/personal/user/99/",
      "icon": "https://example.bitrix24.com/.../avatar.png",
      "workPosition": null
    },
    "responsible": {
      "id": "79",
      "name": "John Smith",
      "link": "/company/personal/user/79/",
      "icon": "/bitrix/images/tasks/default_avatar.png",
      "workPosition": null
    },
    "newCommentsCount": 0,
    "action": {
      "complete": true,
      "start": true,
      "delegate": true,
      "edit": true,
      "remove": true,
      "defer": true,
      "changeDeadline": true
    }
  }
}

Error response example

404 — task not found:

JSON 
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "task 999999999 not found"
  }
}

Errors

HTTP Code Description
HTTP404 CodeENTITY_NOT_FOUND DescriptionA task with this ID was not found
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the tasks scope
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing

The full list of common API errors — Errors.

Known specifics

Embedded user data. The creator and responsible fields each arrive as a nested object with the name, profile link, and avatar. A separate GET /v1/users/:id call is not required to display the task author.

Type coercion works at the top level and does not descend into objects. The card fields (creator, responsible, group, accomplicesData, auditorsData) are declared as objects and arrive from Bitrix24 as-is — the values inside them stay exactly as the Bitrix24 account returned them, including creator.id as a string ("99"). That is not the same as the top-level createdBy, which arrives as a number. Convert via Number() for arithmetic on a nested identifier.

Value types match the schema. Fields declared as numbers in the schema arrive as numbers — including commentsCount, serviceCommentsCount and chatId, which used to be a string in the list and a number in the card. Yes/no flags arrive as true/false, and empty tags, group, accomplicesData and auditorsData arrive as an empty object {}. Converting via Number(value) is no longer needed.

See also