[{"data":1,"prerenderedAt":7},["ShallowReactive",2],{"docs-workday\u002Ftime-control-reports":3,"docs-tabs-workday\u002Ftime-control-reports":6},{"content":4,"lastmod":5},"## Get the monthly absence report\n\n`GET \u002Fv1\u002Fworkday\u002Ftime-control\u002Freports`\n\nReturns an employee's monthly time-control report: workdays, time worked, and absences with explanations. Call it to find an absence and explain it, or to check how much an employee worked in a month.\n\nRequires the `timeman` scope. Permissions are checked for the credential owner: for a personal key, that is the key owner; for an app key, the user whose session token is passed in `Authorization`. Access to reports depends on the role and the [time-control settings](\u002Fdocs\u002Fworkday\u002Ftime-control-settings-list): an administrator and an employee with the full report get the report of any employee, a department head gets the reports of employees in their departments, and an employee with the simple report gets only their own. The `reportViewType` field on the [Get time-control report settings](\u002Fdocs\u002Fworkday\u002Ftime-control-report-settings) page shows which reports are available to the credential owner. While time control is switched off, an employee without subordinates gets `403 BITRIX_ACCESS_DENIED` even for their own report. READONLY keys can read the report.\n\nThe generic `filter` parameter is not applied by this endpoint. By default, the API preserves the previous HTTP 200 response and data, adds `Warning: 299 - \"filter is not supported on this endpoint and was ignored\"`, and records unsupported-filter use in the server log.\n\n## Parameters\n\n| Parameter | Type | Required | Default | Description |\n|----------|-----|:-----:|-----------|----------|\n| `userId` (query) | integer | yes | — | Employee ID, a positive integer. Your own ID is the `userId` field in the [time-control report settings](\u002Fdocs\u002Fworkday\u002Ftime-control-report-settings); IDs of department employees come from [`GET \u002Fv1\u002Fworkday\u002Ftime-control\u002Fusers`](\u002Fdocs\u002Fworkday\u002Ftime-control-users) |\n| `month` (query) | integer | yes | — | Month, from 1 to 12 |\n| `year` (query) | integer | yes | — | Year, a positive integer |\n| `idleMinutes` (query) | number | no | `minimumIdleForReport` from the settings | Minimum break length, in minutes, for a break to count as an absence. Honored in a request from a department head or an administrator, ignored in an employee's request |\n| `workdayHours` (query) | number | no | `8` | Workday length in hours; undertime and overtime are calculated from it |\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fworkday\u002Ftime-control\u002Freports?userId=503&month=5&year=2026\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\"\n```\n\n### curl — OAuth application\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fworkday\u002Ftime-control\u002Freports?userId=503&month=5&year=2026\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\"\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fworkday\u002Ftime-control\u002Freports?userId=503&month=5&year=2026', {\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n  },\n})\nconst { data } = await res.json()\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fworkday\u002Ftime-control\u002Freports?userId=503&month=5&year=2026', {\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n  },\n})\nconst { data } = await res.json()\n```\n\n## Response fields\n\nDates are returned in ISO 8601 format with a time zone, durations in seconds.\n\n| Field | Type | Description |\n|------|-----|----------|\n| `success` | boolean | `true` when the request succeeds |\n| `data.report` | object | Report for the month |\n| `data.report.monthTitle` | string | Month name |\n| `data.report.dateStart` | string | Start of the month |\n| `data.report.dateFinish` | string | End of the month |\n| `data.report.days` | array | Days on which the employee opened a workday. For an existing employee, an empty array means there is no time-tracking data for the month: the employee did not open a workday, or time control is not set up in the Bitrix24 account. To check, see the `active` field in the [time-control settings](\u002Fdocs\u002Fworkday\u002Ftime-control-settings-list) |\n| `data.report.days[].index` | string | Date in `YYYYMMDD` format |\n| `data.report.days[].dayTitle` | string | Date in the Bitrix24 account's date format |\n| `data.report.days[].workdayDateStart` | string | Workday start |\n| `data.report.days[].workdayDateFinish` | string | Workday end. If the day is still open, this is the time the report was built |\n| `data.report.days[].workdayComplete` | boolean | Whether the workday is closed |\n| `data.report.days[].workdayDuration` | integer | Workday duration including breaks |\n| `data.report.days[].workdayDurationFinal` | integer | Time worked, excluding breaks, personal absences, and unexplained absences |\n| `data.report.days[].workdayDurationConfig` | integer | Workday duration according to `workdayHours` |\n| `data.report.days[].workdayTimeLeaksUser` | integer | Breaks the employee recorded themselves |\n| `data.report.days[].workdayTimeLeaksReal` | integer | Breaks according to automatic tracking, including personal and unexplained absences |\n| `data.report.days[].workdayTimeLeaksFinal` | integer | Undertime as a positive number, or overtime as a negative number |\n| `data.report.days[].reports` | array | Absences and events of the workday |\n| `data.report.days[].reports[].id` | string | Record ID. For an absence, it can be used as `absenceId` when [explaining an absence](\u002Fdocs\u002Fworkday\u002Ftime-control-explain) |\n| `data.report.days[].reports[].userId` | string | Employee ID |\n| `data.report.days[].reports[].type` | string | Record type: `IDLE` — the employee stepped away; `OFFLINE` — offline; `TM_START`, `TM_PAUSE`, `TM_CONTINUE`, `TM_END` — start, pause, resumption, and end of the workday; `DESKTOP_ONLINE`, `DESKTOP_OFFLINE`, `DESKTOP_START` — activity of the Bitrix24 desktop app. Only a department head sees the last three types |\n| `data.report.days[].reports[].dateStart` | string | Record start |\n| `data.report.days[].reports[].dateFinish` | string | Record end. If the record is active, this is the time the report was built |\n| `data.report.days[].reports[].duration` | integer | Record duration |\n| `data.report.days[].reports[].active` | boolean | Whether the record is still ongoing |\n| `data.report.days[].reports[].entryId` | string | ID of the workday the record belongs to |\n| `data.report.days[].reports[].reportType` | string | Explanation type: `WORK` — work-related, `PRIVATE` — personal. Any other value means there is no explanation, and the absence counts as personal |\n| `data.report.days[].reports[].reportText` | string | Explanation text |\n| `data.report.days[].reports[].systemText` | string \\| null | Reason recorded by Bitrix24. Only a department head sees it |\n| `data.report.days[].reports[].sourceStart` | string | Source of the record start: `TM_EVENT` — a workday action; `IDLE_EVENT` — the \"Away\" status; `ONLINE_EVENT` — signing in to the Bitrix24 account; `OFFLINE_AGENT` — switching to the \"Offline\" status; `DESKTOP_ONLINE_EVENT`, `DESKTOP_START_EVENT`, `DESKTOP_OFFLINE_AGENT` — the desktop app being turned on and off |\n| `data.report.days[].reports[].sourceFinish` | string | Source of the record end; values as in `sourceStart` |\n| `data.report.days[].reports[].ipStart` | string | IP address at the record start. Only a department head sees it |\n| `data.report.days[].reports[].ipFinish` | string | IP address at the record end. Only a department head sees it |\n| `data.report.days[].reports[].ipStartNetwork` | boolean \\| object | `false` if the IP address at the record start belongs to the office network; otherwise an object with the `ip`, `range`, and `name` fields — the address, the range, and the range name. Only a department head sees it |\n| `data.report.days[].reports[].ipFinishNetwork` | boolean \\| object | The same for the record end |\n| `data.user` | object \\| false | Employee the report is built for, or `false` if the employee does not exist. The `data.user.*` fields below are returned only for an employee object |\n| `data.user.id` | integer | Employee ID |\n| `data.user.active` | boolean | Whether the employee is active |\n| `data.user.name` | string | First and last name |\n| `data.user.firstName` | string | First name |\n| `data.user.lastName` | string | Last name |\n| `data.user.workPosition` | string | Position |\n| `data.user.avatar` | string | Profile photo URL. An empty string if there is no photo |\n| `data.user.personalGender` | string | Gender: `M` or `F` |\n| `data.user.lastActivityDate` | string | Last activity time in the Bitrix24 account |\n\n## Response example\n\nResponse to a department head, one workday:\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"report\": {\n      \"monthTitle\": \"May\",\n      \"dateStart\": \"2026-05-01T00:00:00+00:00\",\n      \"dateFinish\": \"2026-05-31T23:59:59+00:00\",\n      \"days\": [\n        {\n          \"index\": \"20260526\",\n          \"dayTitle\": \"26.05.2026\",\n          \"workdayDateStart\": \"2026-05-26T09:02:11+00:00\",\n          \"workdayDateFinish\": \"2026-05-26T18:05:40+00:00\",\n          \"workdayComplete\": true,\n          \"workdayTimeLeaksUser\": 3600,\n          \"workdayTimeLeaksFinal\": -9,\n          \"workdayDuration\": 32609,\n          \"workdayDurationFinal\": 28809,\n          \"workdayDurationConfig\": 28800,\n          \"workdayTimeLeaksReal\": 3800,\n          \"reports\": [\n            {\n              \"id\": \"153\",\n              \"userId\": \"503\",\n              \"type\": \"IDLE\",\n              \"dateStart\": \"2026-05-26T14:10:05+00:00\",\n              \"dateFinish\": \"2026-05-26T14:30:12+00:00\",\n              \"duration\": 1207,\n              \"active\": false,\n              \"entryId\": \"2237\",\n              \"reportType\": \"WORK\",\n              \"reportText\": \"Client meeting\",\n              \"systemText\": null,\n              \"sourceStart\": \"IDLE_EVENT\",\n              \"sourceFinish\": \"IDLE_EVENT\",\n              \"ipStart\": \"203.0.113.24\",\n              \"ipFinish\": \"203.0.113.24\",\n              \"ipStartNetwork\": false,\n              \"ipFinishNetwork\": false\n            }\n          ]\n        }\n      ]\n    },\n    \"user\": {\n      \"id\": 503,\n      \"active\": true,\n      \"name\": \"Anna Smith\",\n      \"firstName\": \"Anna\",\n      \"lastName\": \"Smith\",\n      \"workPosition\": \"Manager\",\n      \"avatar\": \"\",\n      \"personalGender\": \"F\",\n      \"lastActivityDate\": \"2026-05-29T17:15:56+00:00\"\n    }\n  }\n}\n```\n\n## Error response example\n\n400 — a required parameter is missing or a threshold is not a number:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"INVALID_PARAMS\",\n    \"message\": \"userId, month (1..12), year are required; optional thresholds must be numeric\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|----------|\n| 200 | `Warning: 299` | The filter is ignored by default; previous data is preserved and the warning is sent in the `Warning` header. |\n| 400 (strict mode only) | `UNSUPPORTED_FILTER` | The server mode is disabled by default; until it is enabled, the endpoint preserves HTTP 200 and the previous data. |\n| 400 | `INVALID_PARAMS` | `userId`, `month`, or `year` is missing or is not a positive integer, `month` is greater than 12, `idleMinutes` or `workdayHours` is not a number |\n| 403 | `BITRIX_ACCESS_DENIED` | The role and time-control settings do not give the credential owner access to this employee's report: an employee with the simple report requested someone else's report, a department head without the full report requested the report of an employee outside their departments, or an employee without subordinates requested their own report while time control is switched off |\n| 409 | `TIMEMAN_MODULE_NOT_ENABLED` | Time Management is not available on this portal: the Time Management tool is switched off in the portal settings, or the module is not included in the plan |\n| 502 | `BITRIX_UNAVAILABLE` | Bitrix24 is unavailable or returned a response of an unexpected shape |\n| 401 | `MISSING_API_KEY` | The `X-Api-Key` header was not passed |\n| 401 | `TOKEN_MISSING` | An app key was sent without a session token in `Authorization: Bearer` |\n| 401 | `INVALID_SESSION` | The session token is invalid or has expired |\n| 403 | `SCOPE_DENIED` | The key lacks the `timeman` scope |\n| 429 | `RATE_LIMITED` | The general request limit was exceeded; the retry delay is in the `Retry-After` header |\n\nThe full list of common API errors — [Errors](\u002Fdocs\u002Ferrors).\n\n## Known specifics\n\n**A nonexistent employee is returned without an error.** For a nonexistent `userId`, the method returns `200`: `success` is `true`, `data.user` is `false`, and `data.report.days` is an empty array. The indicator that the employee does not exist is `data.user === false`, rather than `success`: that field indicates a successful request, not that the employee exists. Check `data.user` before interpreting empty days as \"there were no absences\".\n\n**Employee IP addresses are personal data.** The `ipStart`, `ipFinish`, `ipStartNetwork`, and `ipFinishNetwork` fields are returned only to a department head and an administrator. Store and display them according to your company's personal data processing rules.\n\n**Thresholds are rounded, and an out-of-range year is replaced with the current one.** Fractional `idleMinutes` and `workdayHours` are converted to integers, and `workdayHours` less than 1 is treated as 1. A year less than 1900 or greater than 3000 is replaced with the current year without an error, so compare the report's `dateStart` with the requested month.\n\n## See also\n\n- [Get time-control report settings](\u002Fdocs\u002Fworkday\u002Ftime-control-report-settings)\n- [List department employees](\u002Fdocs\u002Fworkday\u002Ftime-control-users)\n- [Explain an absence](\u002Fdocs\u002Fworkday\u002Ftime-control-explain)\n- [Time-control settings](\u002Fdocs\u002Fworkday\u002Ftime-control-settings)\n- [Workday history](\u002Fdocs\u002Fworkday\u002Frecords)\n- [Workday](\u002Fdocs\u002Fworkday)\n","2026-10-23",{},1795000592812]