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

Task time tracking

Time-tracking entries are a nested resource of a task. Each entry has a duration, an author, a comment, and a creation time. The base path is /v1/tasks/:taskId/time. These operations require an existing task :taskId in the Bitrix24 account. Entries from every task at once are served by a separate path, /v1/task-time.

Bitrix24 API: task.elapseditem.* Scope: task

Add a time-tracking entry

POST /v1/tasks/:taskId/time

Creates a new time-tracking entry for a task — records the seconds spent and, optionally, the author of the entry and a comment on it.

Parameters

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

Request fields (body)

Field Type Required Description
Fieldseconds Typenumber Requiredyes DescriptionDuration in seconds
Fieldcomment Typestring Requiredno DescriptionComment for the entry. When the entry is read back, it is returned in the commentText field
FielduserId Typenumber Requiredno DescriptionAuthor ID. Defaults to the API-key user. Pass only existing employee IDs from GET /v1/users — see "Known specifics"
FieldcreatedDate Typestring Requiredno DescriptionDate and time of the entry. Three formats are accepted: ISO 8601 with offset 2026-07-13T14:30:00+00:00, ISO 8601 without offset 2026-07-13T14:30:00, and a date 2026-07-13. If the field is omitted, the entry is dated at the time it is created

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/tasks/289/time" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "seconds": 1800,
    "comment": "Draft preparation"
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/tasks/289/time" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "seconds": 1800,
    "comment": "Draft preparation"
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/tasks/289/time', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    seconds: 1800,
    comment: 'Draft preparation',
  }),
})

const { success, data } = await res.json()
console.log('New entry ID:', data.id)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/tasks/289/time', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    seconds: 1800,
    comment: 'Draft preparation',
  }),
})

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

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.id Typenumber DescriptionID of the created entry. Use it for GET / PATCH / DELETE

Response example

HTTP 201 Created:

JSON 
{
  "success": true,
  "data": {
    "id": 161
  }
}

Error response example

400 — the required seconds field was not provided:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_PARAMS",
    "message": "Required: seconds (number)"
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_PARAMS DescriptionThe seconds field was not provided
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 returned an error (e.g. the parent task is inaccessible)
HTTP403 CodeSCOPE_DENIED DescriptionThe API key lacks the task scope
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens

Full list of common API errors — Errors.

Known specifics

The existence of userId is not validated. The entry is saved with any userId, even a non-existent one, and the call returns 201. But such a "ghost" entry cannot then be read, updated, or deleted — GET, PATCH and DELETE /v1/tasks/:taskId/time/:itemId return 404 NOT_FOUND. It remains visible only in the GET /v1/tasks/:taskId/time and GET /v1/task-time lists, cluttering reports with no way to clean it up via the API. Pass only real employee IDs from GET /v1/users.

The response contains only id, without the other fields. Unlike creating a task or comment, this method returns only the identifier. To get the full entry with minutes, source, createdDate, dateStart and dateStop filled in by the system, call GET /v1/tasks/:taskId/time/:itemId.

See also