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

List entries across the whole Bitrix24 account

GET /v1/task-time

Returns time-tracking entries from all tasks in the Bitrix24 account in a single request, with filtering by employee, period and task. Use it when the list of tasks is not known in advance — for example, for an employee's monthly time report.

Parameters

Parameter Type Default Description
ParameteruserId (query) Typenumber Default— DescriptionEmployee identifier. List: GET /v1/users. If omitted, the response includes entries for all employees the key owner can access
Parameterfrom (query) Typestring Default— DescriptionLower bound of the period, inclusive, by the createdDate field. Accepts ISO 8601 2026-05-01T00:00:00+00:00 and a plain date 2026-05-01
Parameterto (query) Typestring Default— DescriptionUpper bound of the period, inclusive, by the createdDate field. Same format as from. A plain date covers the whole day
ParametertaskId (query) Typenumber Default— DescriptionNarrow the result set to a single task, on top of userId, from and to. Identifier: GET /v1/tasks
Parameterlimit (query) Typenumber Default50 DescriptionPage size, from 1 to 500. A value above 500 is clamped to 500
Parameteroffset (query) Typenumber Default0 DescriptionOffset within the result set. Must be a multiple of limit

Pagination. A single call returns up to 500 entries. With a limit above 50, Vibecode assembles the window server-side and returns it in full. The offset value must be a multiple of limit — 0, limit, 2 × limit, and so on, otherwise 400 INVALID_OFFSET is returned. meta.hasMore indicates whether more entries exist beyond the window.

Filter format. The generic filter envelope is not supported. Use the named query parameters userId, taskId, from, and to. Any bracket key filter[...], a non-empty filter value, a JSON form including filter={}, or a repeated filter parameter returns 400 UNSUPPORTED_FILTER. A single empty filter= parameter means no filter and preserves status 200.

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/task-time?userId=1&from=2026-05-01&to=2026-05-31" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/task-time?userId=1&from=2026-05-01&to=2026-05-31" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const url = 'https://vibecode.bitrix24.com/v1/task-time?userId=1&from=2026-05-01&to=2026-05-31'

const res = await fetch(url, {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data, meta } = await res.json()
const totalSeconds = data.reduce((sum, r) => sum + r.seconds, 0)
console.log(`For the period: ${totalSeconds / 3600} h, ${meta.total} entries`)

JavaScript — OAuth application

javascript 
const url = 'https://vibecode.bitrix24.com/v1/task-time?userId=1&from=2026-05-01&to=2026-05-31'

const res = await fetch(url, {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

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

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typearray DescriptionArray of time-tracking entries
Fielddata[].id Typenumber DescriptionEntry identifier
Fielddata[].taskId Typenumber DescriptionParent task identifier. Card: GET /v1/tasks/:id
Fielddata[].userId Typenumber DescriptionEntry author. Profile: GET /v1/users/:userId
Fielddata[].seconds Typenumber DescriptionDuration in seconds
Fielddata[].minutes Typenumber DescriptionDuration in minutes, derived from seconds
Fielddata[].commentText Typestring DescriptionComment for the entry. An empty comment is returned as ""
Fielddata[].source Typestring DescriptionSource: 2 — REST API
Fielddata[].createdDate Typedatetime DescriptionWhen the entry was created
Fielddata[].dateStart Typedatetime DescriptionStart of the tracked interval, filled automatically
Fielddata[].dateStop Typedatetime DescriptionEnd of the tracked interval, filled automatically
Fieldmeta.total Typenumber DescriptionTotal number of entries matching the filter
Fieldmeta.limit Typenumber DescriptionApplied page size
Fieldmeta.offset Typenumber DescriptionApplied offset
Fieldmeta.hasMore Typeboolean DescriptionWhether there are more entries beyond the current window

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "id": 161,
      "taskId": 3881,
      "userId": 1,
      "commentText": "Code review",
      "seconds": 900,
      "minutes": 15,
      "source": "2",
      "createdDate": "2026-05-13T16:15:41+00:00",
      "dateStart": "2026-05-13T17:15:41+00:00",
      "dateStop": "2026-05-13T17:15:41+00:00"
    },
    {
      "id": 159,
      "taskId": 3867,
      "userId": 1,
      "commentText": "Build check",
      "seconds": 600,
      "minutes": 10,
      "source": "2",
      "createdDate": "2026-05-06T10:46:12+00:00",
      "dateStart": "2026-05-06T11:46:12+00:00",
      "dateStop": "2026-05-06T11:46:12+00:00"
    },
    {
      "id": 157,
      "taskId": 289,
      "userId": 1,
      "commentText": "Draft preparation",
      "seconds": 1800,
      "minutes": 30,
      "source": "2",
      "createdDate": "2026-05-06T10:45:47+00:00",
      "dateStart": "2026-05-06T11:45:47+00:00",
      "dateStop": "2026-05-06T11:45:47+00:00"
    }
  ],
  "meta": {
    "total": 3,
    "limit": 50,
    "offset": 0,
    "hasMore": false
  }
}

Error response example

400 — userId is not a positive integer:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_USER_ID",
    "message": "userId must be a positive integer"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_USER_ID DescriptionuserId is not a positive integer
HTTP400 CodeINVALID_TASK_ID DescriptiontaskId is not a positive integer
HTTP400 CodeINVALID_PARAMS Descriptionfrom or to cannot be parsed as a date — YYYY-MM-DD and ISO 8601 are accepted
HTTP400 CodeINVALID_OFFSET Descriptionoffset is not a multiple of limit — pagination requires the values 0, limit, 2 × limit, and so on
HTTP400 CodeUNSUPPORTED_FILTER DescriptionAn unsupported filter was provided; use userId, taskId, from, and to
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

Sorted newest to oldest. The most recently added entries are returned first. limit and offset work on top of this sort.

A malformed date is refused up front. A from or to value that cannot be parsed as a date answers 400 INVALID_PARAMS before Bitrix24 is called. It used to be dropped in silence and the whole range came back with status 200, so a typo in a date read as either "nothing in that period" or a full dump. An empty value (?from=) still means "no filter".

An offset past the end of the result set. A request whose offset exceeds the number of entries returns an empty array, and meta.total in that response echoes the offset. Detect the end of the listing by meta.hasMore being false, not by comparing offset with meta.total.

See also