{% note tip "" %}
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.
{% endnote %}
Scope:
taskWho can execute the method: any user with read access to the task
The method tasks.task.startwatch enables watching a task.
{% include Note on required parameters %}
#|
|| Name
type | Description ||
|| taskId*
integer | The identifier of the task.
The task identifier can be obtained when creating a new task or by using the get task list method || |#
{% include Note on Examples %}
{% list tabs %}
-
cURL (Webhook)
curl -X POST \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{"taskId":8017}' \ https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/tasks.task.startwatch
-
cURL (OAuth)
curl -X POST \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{"taskId":8017,"auth":"**put_access_token_here**"}' \ https://**put_your_bitrix24_address**/rest/tasks.task.startwatch
-
JS (TS)
// This snippet is an ES module: top-level await requires type="module" or a bundler. // $b24 is an already-initialized SDK instance (see the SDK "Get started" guide). import { Text } from '@bitrix24/b24jssdk' import type { B24Frame, ISODate } from '@bitrix24/b24jssdk' declare const $b24: B24Frame type TaskData = { id: string title: string status: string responsibleId: string createdDate: ISODate | null deadline: ISODate | null } // Shape of the payload returned in result (match the "response handling" section of the page) type TaskStartWatchResult = { task: TaskData } try { const response = await $b24.actions.v2.call.make<TaskStartWatchResult>({ method: 'tasks.task.startwatch', params: { taskId: 8017, }, requestId: Text.getUuidRfc4122() }) // The payload is available only on a successful response if (!response.isSuccess) { console.error(response.getErrorMessages().join('; ')) } else { const result = response.getData()!.result console.info('Watching task:', result.task.id, result.task.title, result.task.status) } } catch (error) { // Thrown on transport or SDK failures (AjaxError, SdkError, etc.) console.error(error) }
-
JS (UMD)
<!-- Load the SDK (UMD build); it is exposed as the global B24Js --> <script src="https://unpkg.com/@bitrix24/b24jssdk@1/dist/umd/index.min.js"></script> <script> async function startWatchTask() { try { // Initialize the SDK inside a Bitrix24 frame const $b24 = await B24Js.initializeB24Frame() const response = await $b24.actions.v2.call.make({ method: 'tasks.task.startwatch', params: { taskId: 8017, }, requestId: B24Js.Text.getUuidRfc4122() }) // The payload is available only on a successful response if (!response.isSuccess) { console.error(response.getErrorMessages().join('; ')) return } const result = response.getData().result console.info('Watching task:', result.task.id, result.task.title, result.task.status) } catch (error) { // Thrown on transport or SDK failures (AjaxError, SdkError, etc.) console.error(error) } } document.addEventListener('DOMContentLoaded', startWatchTask) </script>
-
PHP
try { $response = $b24Service ->core ->call( 'tasks.task.startwatch', [ 'taskId' => 8017 ] ); $result = $response ->getResponseData() ->getResult(); echo 'Success: ' . print_r($result, true); processData($result); } catch (Throwable $e) { error_log($e->getMessage()); echo 'Error starting task watch: ' . $e->getMessage(); }
-
BX24.js
BX24.callMethod( 'tasks.task.startwatch', { 'taskId': 8017 }, function(result){ console.info(result.data()); console.log(result); } );
-
PHP CRest
require_once('crest.php'); $result = CRest::call( 'tasks.task.startwatch', [ 'taskId' => 8017 ] ); echo '<PRE>'; print_r($result); echo '</PRE>';
-
Go
// client and ctx are already created — see the Go SDK section res, err := client.Core().Call(ctx, "tasks.task.startwatch", b24.Params{ "taskId": 8017, }) if err != nil { return fmt.Errorf("tasks.task.startwatch: %w", err) } keys, ok := b24.Keys(res.Result) if !ok { return fmt.Errorf("expected an object in the response") } fmt.Println("fields in response:", len(keys))
{% endlist %}
HTTP Status: 200
{
"result": {
"task": {
"id": "8017",
"parentId": "7817",
"title": "Task Example",
"description": "Task description with [B]formatting[/B]",
"mark": "P",
"priority": "2",
"multitask": "N",
"notViewed": "N",
"replicate": "Y",
"stageId": "395",
"sprintId": null,
"backlogId": null,
"createdBy": "503",
"createdDate": "2025-06-04T16:15:55+02:00",
"responsibleId": "503",
"changedBy": "503",
"changedDate": "2025-09-10T17:22:12+02:00",
"statusChangedBy": "503",
"closedBy": "0",
"closedDate": null,
"activityDate": "2025-09-10T17:22:13+02:00",
"dateStart": "2025-09-10T15:22:12+02:00",
"deadline": "2025-09-11T08:00:00+02:00",
"startDatePlan": null,
"endDatePlan": null,
"guid": "{21e7b78d-498e-4c84-a896-2dbeb26861b8}",
"xmlId": null,
"commentsCount": "44",
"serviceCommentsCount": "28",
"allowChangeDeadline": "Y",
"allowTimeTracking": "Y",
"taskControl": "N",
"addInReport": "N",
"forkedByTemplateId": null,
"timeEstimate": "101580",
"timeSpentInLogs": "69963",
"matchWorkTime": "Y",
"forumTopicId": "1273",
"forumId": "11",
"siteId": "s1",
"subordinate": "Y",
"exchangeModified": null,
"exchangeId": null,
"outlookVersion": "52",
"viewedDate": "2025-09-10T17:22:13+02:00",
"sorting": null,
"durationFact": "1166",
"isMuted": "N",
"isPinned": "N",
"isPinnedInGroup": "N",
"flowId": "19",
"descriptionInBbcode": "Y",
"status": "3",
"statusChangedDate": "2025-09-10T15:22:12+02:00",
"durationPlan": "0",
"durationType": "days",
"favorite": "Y",
"groupId": "129",
"auditors": [
"61",
"103",
"503",
"547"
],
"accomplices": [
"3",
"11"
],
"checklist": {
"433": {
"id": "433",
"taskId": "8017",
"createdBy": "503",
"parentId": "431",
"title": "First",
"sortIndex": "0",
"isComplete": "N",
"isImportant": "N",
"toggledBy": null,
"toggledDate": null,
"ufChecklistFiles": false,
"members": [],
"attachments": [],
"entityId": "8017",
"action": {
"modify": true,
"remove": true,
"toggle": true,
"add": true,
"addAccomplice": true
}
},
"431": {
"id": "431",
"taskId": "8017",
"createdBy": "503",
"parentId": 0,
"title": "Checklist 1",
"sortIndex": "0",
"isComplete": "N",
"isImportant": "N",
"toggledBy": null,
"toggledDate": null,
"ufChecklistFiles": false,
"members": [],
"attachments": [],
"entityId": "8017",
"action": {
"modify": true,
"remove": true,
"toggle": true,
"add": true,
"addAccomplice": true
}
},
"435": {
"id": "435",
"taskId": "8017",
"createdBy": "503",
"parentId": "431",
"title": "Second",
"sortIndex": "1",
"isComplete": "N",
"isImportant": "N",
"toggledBy": null,
"toggledDate": null,
"ufChecklistFiles": false,
"members": [],
"attachments": [],
"entityId": "8017",
"action": {
"modify": true,
"remove": true,
"toggle": true,
"add": true,
"addAccomplice": true
}
}
},
"group": {
"id": "129",
"name": "Work Group",
"opened": false,
"membersCount": 1,
"image": "\/bitrix\/images\/socialnetwork\/workgroup\/folder.png",
"additionalData": []
},
"creator": {
"id": "503",
"name": "Maria Johnson",
"link": "\/company\/personal\/user\/503\/",
"icon": "https:\/\/mysite.com\/b17053\/resize_cache\/45749\/c0120a8d7c10d63c83e32398d1ec4d9e\/main\/c89\/c89c6b7301880958ea704b5a8470635c\/4R5A1256.png",
"workPosition": "Administrator"
},
"responsible": {
"id": "503",
"name": "Maria Johnson",
"link": "\/company\/personal\/user\/503\/",
"icon": "https:\/\/mysite.com\/b17053\/resize_cache\/45749\/c0120a8d7c10d63c83e32398d1ec4d9e\/main\/c89\/c89c6b7301880958ea704b5a8470635c\/4R5A1256.png",
"workPosition": "Administrator"
},
"accomplicesData": {
"3": {
"id": "3",
"name": "Andrew Karpov",
"link": "\/company\/personal\/user\/3\/",
"icon": "https:\/\/mysite.com\/b17053\/resize_cache\/249\/c0120a8d7c10d63c83e32398d1ec4d9e\/main\/cd526b0644e7ff4d794ea41cb36bc423\/odmin.png",
"workPosition": "System Administrator"
},
"11": {
"id": "11",
"name": "Andrew Sergeev",
"link": "\/company\/personal\/user\/11\/",
"icon": "https:\/\/mysite.com\/b17053\/resize_cache\/231\/c0120a8d7c10d63c83e32398d1ec4d9e\/main\/026bf59e161a0bd50f401d3796800651\/66b.jpg",
"workPosition": "Specialist"
}
},
"auditorsData": {
"61": {
"id": "61",
"name": "Ivan Petrov",
"link": "\/company\/personal\/user\/61\/",
"icon": "https:\/\/mysite.com\/b17053\/resize_cache\/8674\/c0120a8d7c10d63c83e32398d1ec4d9e\/main\/7b5\/7b52e4c2304ec0520dab3d4261e9ca1f\/sp.jpg",
"workPosition": "Marketer"
},
"103": {
"id": "103",
"name": "Svetlana Ivanova",
"link": "\/company\/personal\/user\/103\/",
"icon": "https:\/\/mysite.com\/b17053\/resize_cache\/8644\/c0120a8d7c10d63c83e32398d1ec4d9e\/main\/45f\/45fff10d17d398a5583184c8350cd197\/buh.jpg",
"workPosition": "Accountant"
},
"503": {
"id": "503",
"name": "Maria Johnson",
"link": "\/company\/personal\/user\/503\/",
"icon": "https:\/\/mysite.com\/b17053\/resize_cache\/45749\/c0120a8d7c10d63c83e32398d1ec4d9e\/main\/c89\/c89c6b7301880958ea704b5a8470635c\/4R5A1256.png",
"workPosition": "Administrator"
},
"547": {
"id": "547",
"name": "Maria",
"link": "\/company\/personal\/user\/547\/",
"icon": "\/bitrix\/images\/tasks\/default_avatar.png",
"workPosition": "Tester"
}
},
"newCommentsCount": 0,
"action": {
"accept": false,
"decline": false,
"complete": true,
"approve": false,
"disapprove": false,
"start": false,
"pause": true,
"delegate": true,
"remove": true,
"edit": true,
"defer": false,
"renew": false,
"create": true,
"changeDeadline": true,
"checklistAddItems": true,
"addFavorite": false,
"deleteFavorite": true,
"rate": true,
"take": false,
"edit.originator": false,
"checklist.reorder": true,
"elapsedtime.add": true,
"dayplan.timer.toggle": true,
"edit.plan": true,
"checklist.add": true,
"favorite.add": false,
"favorite.delete": true
},
"checkListTree": {
"nodeId": 0,
"fields": {
"id": null,
"copiedId": null,
"entityId": null,
"userId": 503,
"createdBy": null,
"parentId": null,
"title": "",
"sortIndex": null,
"displaySortIndex": "",
"isComplete": false,
"isImportant": false,
"completedCount": 0,
"members": [],
"attachments": [],
"nodeId": null
},
"action": [],
"descendants": [
{
"nodeId": 1,
"fields": {
"id": 431,
"copiedId": null,
"entityId": 8017,
"userId": 503,
"createdBy": 503,
"parentId": 0,
"title": "Checklist 1",
"sortIndex": 0,
"displaySortIndex": "",
"isComplete": false,
"isImportant": false,
"completedCount": 0,
"members": [],
"attachments": [],
"nodeId": null
},
"action": {
"modify": true,
"remove": true,
"toggle": true,
"add": true,
"addAccomplice": true
},
"descendants": [
{
"nodeId": 2,
"fields": {
"id": 433,
"copiedId": null,
"entityId": 8017,
"userId": 503,
"createdBy": 503,
"parentId": 431,
"title": "First",
"sortIndex": 0,
"displaySortIndex": "1",
"isComplete": false,
"isImportant": false,
"completedCount": 0,
"members": [],
"attachments": [],
"nodeId": null
},
"action": {
"modify": true,
"remove": true,
"toggle": true,
"add": true,
"addAccomplice": true
},
"descendants": []
},
{
"nodeId": 3,
"fields": {
"id": 435,
"copiedId": null,
"entityId": 8017,
"userId": 503,
"createdBy": 503,
"parentId": 431,
"title": "Second",
"sortIndex": 1,
"displaySortIndex": "2",
"isComplete": false,
"isImportant": false,
"completedCount": 0,
"members": [],
"attachments": [],
"nodeId": null
},
"action": {
"modify": true,
"remove": true,
"toggle": true,
"add": true,
"addAccomplice": true
},
"descendants": []
}
]
}
]
},
"checkListCanAdd": true
},
"time": {
"start": 1757514132.671783,
"finish": 1757514133.47723,
"duration": 0.8054471015930176,
"processing": 0.7846410274505615,
"date_start": "2025-09-10T17:22:12+02:00",
"date_finish": "2025-09-10T17:22:13+02:00",
"operating_reset_at": 1757514732,
"operating": 0.7846250534057617
}
}
}#|
|| Name
type | Description ||
|| result
object | Object containing the response data ||
|| task
object | Object with task description after the operation is performed ||
|| time
time | Information about the request execution time ||
|#
HTTP Status: 400
{
"error":"0",
"error_description":"wrong task id"
}{% include notitle error handling %}
#|
|| Code | Description | Value ||
|| 0 | wrong task id | The value of taskId is of an incorrect type ||
|| 1048584 | a:0:{} | This error is returned in cases:
- The task with the specified
IDdoes not exist - No access to the task || |#
{% include system errors %}