# 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`

## Operations

- [Add an entry](./time/create.md) — `POST /v1/tasks/:taskId/time`
- [List time-tracking entries](./time/list.md) — `GET /v1/tasks/:taskId/time`
- [Get a time-tracking entry](./time/get.md) — `GET /v1/tasks/:taskId/time/:itemId`
- [Update a time-tracking entry](./time/update.md) — `PATCH /v1/tasks/:taskId/time/:itemId`
- [Delete a time-tracking entry](./time/delete.md) — `DELETE /v1/tasks/:taskId/time/:itemId`
- [List entries across the whole Bitrix24 account](./time/global-list.md) — `GET /v1/task-time`
- [Entry fields](./time/fields.md) — `GET /v1/task-time/fields`

## Key fields

The same fields are served by the machine-readable schema [`GET /v1/task-time/fields`](./time/fields.md) — type, read-only flag, label and description for each.

| Field | Type | Description |
|------|-----|---------|
| `id` | number | Entry identifier |
| `taskId` | number | Parent task ID |
| `userId` | number | Author. Employee list: `GET /v1/users` |
| `seconds` | number | Duration in seconds. The primary field, set at creation |
| `minutes` | number | Duration in minutes, derived from `seconds`, filled by the system |
| `commentText` | string | Comment for the entry. An empty comment is returned as `""`, not `null` |
| `source` | string | Source: `2` — the entry was created through the REST API |
| `createdDate` | datetime | Entry creation date |
| `dateStart`, `dateStop` | datetime | Start and end of the tracked interval. Filled automatically and not editable through the current API |

## What to know before you start

1. **Response fields are in camelCase.** Time-tracking entries are returned in camelCase — `id`, `taskId`, `userId`, `seconds`, `minutes`, `commentText`, `source`, `createdDate`, `dateStart`, `dateStop` — like task comments and the rest of the API.
2. **Numeric values are returned as numbers, `source` as a string.** `id`, `taskId`, `userId`, `seconds`, and `minutes` are serialized as numbers — for example `"seconds": 900`. This holds across every response — in list responses and in a single entry alike — so you do not need to convert them with `Number(value)`. The `source` field stays a string: `"source": "2"`.
3. **`seconds` is the only unit of measurement on write.** The `seconds` parameter is required. The system recalculates `minutes` itself.
4. **Entries are deleted together with the task.** If the parent task is deleted ([`DELETE /v1/tasks/:id`](./delete.md)), its time-tracking entries become inaccessible — a separate `DELETE` for each is not required. Requesting them by their previous ID returns `404`.
5. **`dateStart` and `dateStop` are not editable through the API.** Their values are filled by Bitrix24 automatically at the moment the entry is created. To record a specific interval, pass the total time via `seconds` in `POST` or `PATCH`. Bitrix24 consistently sets the interval about an hour ahead of `createdDate` — that is its own auto-fill, and the Vibecode API does not change the dates.
6. **The list may show entries you cannot fetch individually.** The lists — both the global one and the one for a single task — sometimes return entries belonging to others. Requesting such an entry by its `itemId` returns `404 NOT_FOUND`. This is an access-rights mismatch on the Bitrix24 side.
7. **The field schema lives on the flat path.** The field set is served by `GET /v1/task-time/fields`. The nested `GET /v1/tasks/:taskId/time/fields` returns `400 WRONG_PATH` and names the correct path in the error text: the schema is the same for every task, so it is not repeated under each `:taskId`. The request needs the `task` scope and makes no Bitrix24 call.
8. **`userId` is set on creation only.** `POST` accepts it, `PATCH` returns `400 READONLY_FIELD` — Bitrix24 cannot move an entry to another employee. The field schema marks it `createOnly`.
9. **The comment is named differently in the response and in the request body.** It is returned as `commentText` and passed as `comment` on write.

## Typical scenario

1. Find or create a task: [`GET /v1/tasks`](./list.md) / [`POST /v1/tasks`](./create.md).
2. Add an entry: [`POST /v1/tasks/:taskId/time`](./time/create.md) with `seconds` and, if needed, `comment` and `userId`.
3. View the tracking history: [`GET /v1/tasks/:taskId/time`](./time/list.md).
4. Adjust the duration or comment: [`PATCH /v1/tasks/:taskId/time/:itemId`](./time/update.md).
5. Delete an erroneous entry: [`DELETE /v1/tasks/:taskId/time/:itemId`](./time/delete.md).
6. Build a report for one employee over a period without iterating over tasks: [`GET /v1/task-time`](./time/global-list.md).

## Limits

| Limit | Value |
|-------|----------|
| Entries per page | 1..500, 50 by default |
| Request rate | shared across the Vibecode API — see [Limits and optimization](/docs/optimization) |

## See also

- [Tasks](../tasks.md)
- [Task comments](../task-comments.md)
- [Employees](/docs/entities/users)
- [Limits and optimization](/docs/optimization)