Workday history

GET /v1/workday/records

Returns an employee's workday history: start and end times, seconds worked, break durations, and an offset calculated for each record from the current IANA time zone (TIME_ZONE) in the employee profile. Records are selected by the required employee identifier and a period; without a period the window covers the last 7 days.

This endpoint requires both timeman and one of user_brief, user_basic, or user. An empty page is returned without an additional profile lookup. If the current IANA profile zone cannot be retrieved or its historical rules cannot yield an offset for a non-empty page, the endpoint returns 502 BITRIX_UNAVAILABLE with no partial data. The API cannot detect a zone reassignment after record creation, so that case does not produce a 502.

Parameters

Both ends of the period are optional: if neither from nor to is passed, the selection is limited to the last 7 days from the moment of the request. A query parameter outside this list returns 400 INVALID_PARAMS with the name of the passed key and the list of accepted ones.

Examples

curl — personal key

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://vibecode.bitrix24.com/v1/workday/records?userId=1&from=2020-01-01T00:00:00Z&limit=3&order=asc"

curl — another employee's records

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://vibecode.bitrix24.com/v1/workday/records?userId=503&from=2020-01-01T00:00:00Z&limit=3&order=asc"

curl — OAuth application

curl -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  "https://vibecode.bitrix24.com/v1/workday/records?userId=1&from=2020-01-01T00:00:00Z&limit=3&order=asc"

JavaScript — personal key

const params = new URLSearchParams({
  userId: '1',
  from: '2020-01-01T00:00:00Z',
  limit: '3',
  order: 'asc',
})
const res = await fetch(`https://vibecode.bitrix24.com/v1/workday/records?${params}`, {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { data, meta } = await res.json()
for (const record of data) {
  console.log(record.startTime, '— seconds worked:', record.duration)
}
console.log('More records available:', meta.hasMore)

JavaScript — OAuth application

const params = new URLSearchParams({
  userId: '1',
  from: '2020-01-01T00:00:00Z',
  limit: '3',
  order: 'asc',
})
const res = await fetch(`https://vibecode.bitrix24.com/v1/workday/records?${params}`, {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const { data, meta } = await res.json()

Response fields

Response example

The first three records from oldest to newest, ?userId=1&from=2020-01-01T00:00:00Z&limit=3&order=asc:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "userId": 1,
      "startTime": "2020-04-23T13:42:10+00:00",
      "endTime": "2020-04-23T17:53:26+00:00",
      "duration": 12999,
      "breakLength": 2077,
      "state": { "status": "closed", "recommendedCloseTime": null },
      "isApproved": true,
      "tzOffset": 7200
    },
    {
      "id": 5,
      "userId": 1,
      "startTime": "2020-04-24T09:16:12+00:00",
      "endTime": "2020-04-24T16:30:13+00:00",
      "duration": 26041,
      "breakLength": 0,
      "state": { "status": "closed", "recommendedCloseTime": null },
      "isApproved": true,
      "tzOffset": 7200
    },
    {
      "id": 7,
      "userId": 1,
      "startTime": "2020-04-27T09:04:11+00:00",
      "endTime": "2020-04-27T18:00:00+00:00",
      "duration": 32149,
      "breakLength": 0,
      "state": { "status": "closed", "recommendedCloseTime": null },
      "isApproved": true,
      "tzOffset": 7200
    }
  ],
  "meta": { "hasMore": true, "from": "2020-01-01T00:00:00Z" }
}

The last page of the same selection, ?userId=1&from=2020-01-01T00:00:00Z&offset=40&order=asc — fewer records than limit arrived, so total appears in meta:

{
  "success": true,
  "data": [
    {
      "id": 163,
      "userId": 1,
      "startTime": "2024-07-24T17:34:51+00:00",
      "endTime": "2024-07-25T02:35:00+00:00",
      "duration": 32409,
      "breakLength": 0,
      "state": { "status": "closed", "recommendedCloseTime": null },
      "isApproved": true,
      "tzOffset": 7200
    },
    {
      "id": 165,
      "userId": 1,
      "startTime": "2024-08-26T12:34:47+00:00",
      "endTime": "2024-08-26T12:58:15+00:00",
      "duration": 1408,
      "breakLength": 0,
      "state": { "status": "closed", "recommendedCloseTime": null },
      "isApproved": true,
      "tzOffset": 7200
    },
    {
      "id": 167,
      "userId": 1,
      "startTime": "2024-09-05T12:07:30+00:00",
      "endTime": "2025-03-27T14:53:08+00:00",
      "duration": 17548827,
      "breakLength": 311,
      "state": { "status": "closed", "recommendedCloseTime": null },
      "isApproved": true,
      "tzOffset": 7200
    },
    {
      "id": 171,
      "userId": 1,
      "startTime": "2026-05-05T09:52:51+00:00",
      "endTime": "2026-05-05T09:53:37+00:00",
      "duration": 20,
      "breakLength": 26,
      "state": { "status": "closed", "recommendedCloseTime": null },
      "isApproved": true,
      "tzOffset": 7200
    },
    {
      "id": 173,
      "userId": 1,
      "startTime": "2026-05-05T09:55:38+00:00",
      "endTime": "2026-05-05T09:55:39+00:00",
      "duration": 1,
      "breakLength": 0,
      "state": { "status": "closed", "recommendedCloseTime": null },
      "isApproved": true,
      "tzOffset": 7200
    },
    {
      "id": 175,
      "userId": 1,
      "startTime": "2026-05-05T10:07:02+00:00",
      "endTime": "2026-05-05T10:07:06+00:00",
      "duration": 2,
      "breakLength": 2,
      "state": { "status": "closed", "recommendedCloseTime": null },
      "isApproved": true,
      "tzOffset": 7200
    }
  ],
  "meta": { "hasMore": false, "total": 46, "from": "2020-01-01T00:00:00Z" }
}

Error response example

400 — a required parameter is missing:

{
  "success": false,
  "error": {
    "code": "MISSING_REQUIRED_PARAMS",
    "message": "userId is required. Bitrix24 refuses this method without it; get the id from GET /v1/users/me."
  }
}

Errors

For the full list of common API errors, see Errors.

Known specifics

• The key does not restrict permissions to the caller's identity. A personal key vibe_api_… accesses the Bitrix24 account through an inbound webhook and reads the time sheet with the rights of the Bitrix24 employee the webhook was issued under — that is, the rights of the key creator, not of whoever uses the key. The owner of such a key can enumerate userId and export the clock-in and clock-out times of the whole company. An application key vibe_app_… works differently — the request goes with the rights of the employee who opened the session. Bitrix24, not the platform, decides who may read another employee's time sheet: the Bitrix24 account administrator or the employee's direct manager.
• The response names the period it applied. meta.from and meta.to are present even when no period was passed: otherwise a meta.total of 0 cannot be told apart from "this employee has no records at all", though it only means "none in the last 7 days". For a period left open on one side, only the bound that is set comes back.
• A parameter must not be passed twice. ?userId=1&userId=2 returns 400 instead of silently picking one of the values.
• meta.total arrives only on a short page. On a full page the field is absent from the response entirely, so a handler that reads it unconditionally gets undefined. The value is correct at the time of the response: with order=desc a record added between two requests shifts the output window.
• The offset in startTime and endTime is not the employee's time zone. Both strings keep the account offset and are not rewritten. tzOffset is calculated for the absolute startTime instant using the historical rules of the current IANA time zone (TIME_ZONE) in the employee profile. To get local time in that zone, parse the absolute instant from startTime and apply tzOffset. If another IANA zone was assigned after record creation, the API does not know the former assignment: the returned value belongs to the current profile zone and is not proof of the zone assigned at that time.
• Durations arrive in seconds. duration and breakLength are integer numbers of seconds. The related GET /v1/workday/status returns durations as a string of the form HH:MM:SS, so parsing does not carry over from one page to the other.
• The selection is limited to the employee and the day start time. The endpoint supports no other filters: you cannot filter by end time, duration or approval status, and sorting is by start time only. Filter the returned records locally to obtain the subset you need.
• The whole history is traversed in pages of 50 records. The endpoint does not return more than 50 records per request; deeper pages are reached with offset or page. The end of the output is signaled by meta.hasMore with the value false. A request with an offset beyond the end of the selection returns an empty array, and meta.total does not arrive in such a response.

See also

• Current status
• Open a workday
• Close a workday
• Pause
• Tracking settings
• Work schedule
• Workday

Work and daily reports

Work reports

Daily reports