Get Report on Identified Absences timeman.timecontrol.reports.get

Choose a tool for developing with an AI agent:

use Alaio Vibecode to build an app for Bitrix24 from a task description without knowing any programming language. The agent writes the code and deploys the app to a server, with no manual hosting setup
use the MCP server to develop a REST API integration in your own project. The agent refers to the official REST documentation

Scope: timeman

Who can execute the method: any user with report viewing permission

The method timeman.timecontrol.reports.get retrieves a report on identified absences.

Method Parameters

Required parameters are marked with *

Name `type`	Description
USER_ID* `integer`	User ID for whom the reports are requested. You can obtain the user ID using the user.get method.
MONTH* `integer`	Month number
YEAR* `integer`	Year
IDLE_MINUTES `integer`	Maximum time of absence at the workplace that is not counted as absence. This parameter is available to the manager and administrator. If not specified, the time from the module settings is used.
WORKDAY_HOURS `integer`	Duration of the workday in hours. Default is 8 hours.

Code Examples

How to Use Examples in Documentation

cURL (Webhook)

cURL (OAuth)

JS (TS)

JS (UMD)

Python

PHP

BX24.js

PHP CRest

curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"USER_ID":3,"MONTH":5,"YEAR":2025,"IDLE_MINUTES":15,"WORKDAY_HOURS":8}' \
        https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/timeman.timecontrol.reports.get

curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"USER_ID":3,"MONTH":5,"YEAR":2025,"IDLE_MINUTES":15,"WORKDAY_HOURS":8,"auth":"**put_access_token_here**"}' \
        https://**put_your_bitrix24_address**/rest/timeman.timecontrol.reports.get

// This snippet is an ES module: top-level await requires type="module" or a bundler.
        // $b24 is an already-initialized SDK instance (see the SDK "Get started" guide).
        import { Text } from '@bitrix24/b24jssdk'
        import type { B24Frame, ISODate } from '@bitrix24/b24jssdk'
        
        declare const $b24: B24Frame
        
        // Shape of the payload returned in result (match the "response handling" section of the page)
        type TimecontrolReportResult = {
          report: {
            month_title: string
            date_start: ISODate
            date_finish: ISODate
            days: {
              index: string
              day_title: string
              workday_date_start: ISODate
              workday_date_finish: ISODate
              workday_complete: boolean
              workday_time_leaks_user: number
              workday_time_leaks_final: number
              workday_duration: number
              workday_duration_final: number
              workday_duration_config: number
              reports: {
                id: string
                user_id: string
                type: string
                date_start: ISODate
                date_finish: ISODate
                duration: number
                active: boolean
                entry_id: string
                report_type: string
                report_text: string
                system_text: string | null
                source_start: string
                source_finish: string
                ip_start: string
                ip_finish: string
                ip_start_network: boolean | object
                ip_finish_network: boolean | object
              }[]
              workday_time_leaks_real: number
            }[]
          }
          user: {
            id: number
            active: boolean
            name: string
            first_name: string
            last_name: string
            work_position: string
            avatar: string
            personal_gender: string
            last_activity_date: ISODate
          }
        }
        
        try {
          const response = await $b24.actions.v2.call.make<TimecontrolReportResult>({
            method: 'timeman.timecontrol.reports.get',
            params: {
              USER_ID: 3,
              MONTH: 5,
              YEAR: 2025,
              IDLE_MINUTES: 15,
              WORKDAY_HOURS: 8,
            },
            requestId: Text.getUuidRfc4122()
          })
        
          // The payload is available only on a successful response
          if (!response.isSuccess) {
            console.error(response.getErrorMessages().join('; '))
          } else {
            const result = response.getData()!.result
            console.info(result.report.month_title, result.report.days.length, result.user.name)
          }
        } catch (error) {
          // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
          console.error(error)
        }

<!-- Load the SDK (UMD build); it is exposed as the global B24Js -->
        <script src="https://unpkg.com/@bitrix24/b24jssdk@1/dist/umd/index.min.js"></script>
        <script>
          async function getTimecontrolReport() {
            try {
              // Initialize the SDK inside a Bitrix24 frame
              const $b24 = await B24Js.initializeB24Frame()
        
              const response = await $b24.actions.v2.call.make({
                method: 'timeman.timecontrol.reports.get',
                params: {
                  USER_ID: 3,
                  MONTH: 5,
                  YEAR: 2025,
                  IDLE_MINUTES: 15,
                  WORKDAY_HOURS: 8,
                },
                requestId: B24Js.Text.getUuidRfc4122()
              })
        
              // The payload is available only on a successful response
              if (!response.isSuccess) {
                console.error(response.getErrorMessages().join('; '))
                return
              }
        
              const result = response.getData().result
              console.info(result.report.month_title, result.report.days.length, result.user.name)
            } catch (error) {
              // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
              console.error(error)
            }
          }
        
          document.addEventListener('DOMContentLoaded', getTimecontrolReport)
        </script>

from b24pysdk.errors import BitrixAPIError, BitrixSDKException
        
        try:
            bitrix_response = client.timeman.timecontrol.reports.get(
                user_id=3,
                month=5,
                year=2025,
                idle_minutes=15,
                workday_hours=8,
            ).response
            result = bitrix_response.result
            print(result)
        except BitrixAPIError as error:
            print(
                "Bitrix API error",
                f"error: {error.error}",
                f"error_description: {error.error_description}",
                sep="\n",
            )
        except BitrixSDKException as error:
            print(f"Bitrix SDK error: {error.message}")
        except Exception as error:
            print(f"Unexpected error: {error}")

try {
            $response = $b24Service
                ->core
                ->call(
                    'timeman.timecontrol.reports.get',
                    [
                        'USER_ID'       => 3,
                        'MONTH'         => 5,
                        'YEAR'          => 2025,
                        'IDLE_MINUTES'  => 15,
                        'WORKDAY_HOURS' => 8
                    ]
                );
        
            $result = $response
                ->getResponseData()
                ->getResult();
        
            echo 'Success: ' . print_r($result, true);
            echo 'Info: ' . print_r($result, true);
        
        } catch (Throwable $e) {
            error_log($e->getMessage());
            echo 'Error getting time control reports: ' . $e->getMessage();
        }

BX24.callMethod(
            'timeman.timecontrol.reports.get',
            {
                'USER_ID': 3,
                'MONTH': 5,
                'YEAR': 2025,
                'IDLE_MINUTES': 15,
                'WORKDAY_HOURS': 8
            },
            function(result) {
                if (result.error()) {
                    console.error(result.error());
                } else {
                    console.info(result.data());
                }
            }
        );

require_once('crest.php');
        
        $result = CRest::call(
            'timeman.timecontrol.reports.get',
            [
                'USER_ID' => 3,
                'MONTH' => 5,
                'YEAR' => 2025,
                'IDLE_MINUTES' => 15,
                'WORKDAY_HOURS' => 8
            ]
        );
        
        echo '<PRE>';
        print_r($result);
        echo '</PRE>';

// client and ctx are already created — see the Go SDK section
        res, err := client.Core().Call(ctx, "timeman.timecontrol.reports.get", b24.Params{
        	"USER_ID":       3,
        	"MONTH":         5,
        	"YEAR":          2025,
        	"IDLE_MINUTES":  15,
        	"WORKDAY_HOURS": 8,
        }, b24.WithIdempotent())
        if err != nil {
        	return fmt.Errorf("timeman.timecontrol.reports.get: %w", err)
        }
        
        // The response arrives as json.RawMessage — unmarshal it
        // into a struct matching the response shape shown below on this page.
        fmt.Printf("%s\n", res.Result)

Response Handling

HTTP Status: 200

{
            "result": {
                "report": {
                    "month_title": "May",
                    "date_start": "2025-05-01T00:00:00+02:00",
                    "date_finish": "2025-05-31T23:59:59+02:00",
                    "days": [
                        {
                            "index": "20250526",
                            "day_title": "05/26/2025",
                            "workday_date_start": "2025-05-26T14:44:47+02:00",
                            "workday_date_finish": "2025-05-26T14:45:29+02:00",
                            "workday_complete": true,
                            "workday_time_leaks_user": 0,
                            "workday_time_leaks_final": 28758,
                            "workday_duration": 42,
                            "workday_duration_final": 42,
                            "workday_duration_config": 28800,
                            "reports": [
                                {
                                    "id": "27",
                                    "user_id": "503",
                                    "type": "TM_START",
                                    "date_start": "2025-05-26T14:44:47+02:00",
                                    "date_finish": "2025-05-26T14:44:47+02:00",
                                    "duration": 0,
                                    "active": false,
                                    "entry_id": "2237",
                                    "report_type": "WORK",
                                    "report_text": "Worked on the project",
                                    "system_text": null,
                                    "source_start": "TM_EVENT",
                                    "source_finish": "TM_EVENT",
                                    "ip_start": "83.219.151.30",
                                    "ip_finish": "83.219.151.30",
                                    "ip_start_network": false,
                                    "ip_finish_network": false
                                },
                                {
                                    "id": "29",
                                    ...
                                }
                            ],
                            "workday_time_leaks_real": 0
                        }
                    ]
                },
                "user": {
                    "id": 3,
                    "active": true,
                    "name": "Natalie Brooks",
                    "first_name": "Natalie",
                    "last_name": "Brooks",
                    "work_position": "IT Specialist",
                    "avatar": "http://test.bitrix24.com/upload/resize_cache/45749/7acf4ca766af5d8/main/c89/c89c6b73470635c/4R5A1256.png",
                    "personal_gender": "F",
                    "last_activity_date": "2025-05-29T17:15:56+02:00"
                },
                "time": {
                    "start": 1748528193.688745,
                    "finish": 1748528193.730104,
                    "duration": 0.04135894775390625,
                    "processing": 0.014277935028076172,
                    "date_start": "2025-05-29T17:16:33+02:00",
                    "date_finish": "2025-05-29T17:16:33+02:00",
                    "operating_reset_at": 1748528793,
                    "operating": 0
                }
            }
        }

If the response has empty days

If the method returns an empty array days, configure the time control tool.

Execute the method timeman.timecontrol.settings.set under an administrator with the following parameters:

BX24.callMethod(
            'timeman.timecontrol.settings.set',
            {
                active: true,
                REPORT_SIMPLE_TYPE: 'all',
                REPORT_FULL_TYPE: 'all',
                report_request_type: 'user',
                report_request_users: 3,
            },
            function(result){
                if(result.error())
                {
                    console.error(result.error().ex);
                }
                else
                {
                    console.log(result.data());
                }
            }
        );

Open or close the user's workday.
Execute the method timeman.timecontrol.reports.get. The response will include data in days.

Returned Data

Name `type`	Description
result `object`	Root element of the response
report `object`	Report information
month_title `string`	Month name
date_start `datetime`	Start date of the sampling period in ATOM format
date_finish `datetime`	End date of the sampling period in ATOM format
days `array`	List of objects describing worked days
user `object`	Object with information about the user
time `time`	Information about the request execution time

Objects days

Name `type`	Description
index `integer`	Weekday index in the format `YYYYMMDD`, for example, `20250526` for May 26, 2025
day_title `string`	Date in site format
workday_date_start `datetime`	Start date of the workday in ATOM format
workday_date_finish `datetime`	End date of the workday in ATOM format. If `workday_complete = false`, the date is indicated at the moment of report generation.
workday_complete `boolean`	Workday completed
workday_time_leaks_user `integer`	Duration of break in seconds
workday_time_leaks_final `integer`	Duration of time in seconds that the user underworked or overworked. Positive number — amount of underworked time in seconds Negative number — amount of time worked beyond the required time, i.e., overtime.
workday_duration `integer`	Duration of the workday according to the schedule in seconds, including breaks
workday_duration_final `integer`	Duration of the workday according to actual output in seconds. Includes: breaks unconfirmed absences absences for personal matters.
workday_duration_config `integer`	Required duration of the workday in seconds
reports `array`	List of objects with records of identified absences. Values are displayed in full detail of the report and for the manager.
workday_time_leaks_real `integer`	Duration of break established by the automatic recording system. Contains unconfirmed absences and absences for personal matters.

Objects reports

Name `type`	Description
id `string`	Record ID
user_id `string`	User ID
type `string`	Record type. Possible values: `IDLE` — stepped away, recorded using the desktop application `OFFLINE` — offline `DESKTOP_ONLINE` — launched the application. For manager only `DESKTOP_OFFLINE` — turned off the application. For manager only `DESKTOP_START` — launched the application. For manager only `TM_START` — started the workday `TM_PAUSE` — went on break `TM_CONTINUE` — continued the day `TM_END` — finished the workday
date_start `datetime`	Start date of the recording in ATOM format
date_finish `datetime`	End date of the recording in ATOM format. If `active = true`, the field contains the date at the moment of report generation.
duration `integer`	Duration
active `boolean`	Activity of the record
entry_id `string`	Time record ID
report_type `string`	Absence type. Possible values: `work` — for work matters `private` — for personal matters `none` — type not specified, equated to `private`
report_text `string`	Description of the reason for absence
system_text `string`	System description of the reason for absence. For manager only
source_start `string`	Data source for the start of the record. Possible values: `ONLINE_EVENT` — user authorization event `OFFLINE_AGENT` — agent that sets the Offline status `DESKTOP_OFFLINE_AGENT` — agent that sets the application off status `DESKTOP_ONLINE_EVENT` — event that sets the application on status `DESKTOP_START_EVENT` — event that sets the application on status `IDLE_EVENT` — event changing the status to Stepped Away. Recorded by the application `TM_EVENT` — event changing the workday: start, break, end.
source_finish `string`	Data source for the end of the record. Possible values: `ONLINE_EVENT` — user authorization event `OFFLINE_AGENT` — agent that sets the Offline status `DESKTOP_OFFLINE_AGENT` — agent that sets the application off status `DESKTOP_ONLINE_EVENT` — event that sets the application on status `DESKTOP_START_EVENT` — event that sets the application on status `IDLE_EVENT` — event changing the status to Stepped Away. Recorded by the application `TM_EVENT` — event changing the workday: start, break, end.
ip_start `string`	IP address at the start of the record. For manager only
ip_finish `string`	IP address at the end of the record. For manager only
ip_start_network `boolean` \| `object`	Object with IP address decoding for the start of the record, if the IP address is not within the office network. For office network, it will return `false`. For manager only
ip_finish_network `boolean` \| `object`	Object with IP address decoding for the end of the record, if the IP address is not within the office network. For office network, it will return `false`. For manager only

Object ip_network

Name `type`	Description
ip `string`	IP address
range `string`	Range that includes the specified IP address
name `string`	Name of the range that includes the specified IP address

Object user

Name `type`	Description
id `integer`	User ID
active `boolean`	Activity
name `string`	User's full name
first_name `string`	User's first name
last_name `string`	User's last name
work_position `string`	Position
avatar `string`	User's avatar URL. If the value is empty, the user has no avatar.
personal_gender `string`	User's gender
last_activity_date `datetime`	Date of the user's last action in ATOM format

Error Handling

HTTP Status: 400

{
            "error": "USER_ACCESS_ERROR",
            "error_description": "You don't have access to report for this user"
        }

Name `type`	Description
error `string`	String error code. It consists of digits, Latin letters, and underscores. It may arrive empty — in that case only `error_description` shows the reason
error_description `string`	Error message for the developer. Do not show it to the end user without processing

Possible Error Codes

Code	Description	Value
`ACCESS_ERROR`	You don't have access to this method	You do not have access to this method
`USER_ACCESS_ERROR`	You don't have access to report for this user	You do not have access to this user's reports

Statuses and System Error Codes

HTTP Status: 4xx, 5xx

The errors described below are returned by the REST API itself, not by the logic of a specific method. They can arrive in response to any method.

Status	Code Error Message	Description
`500`	`INTERNAL_SERVER_ERROR` Internal server error	An internal server error has occurred. Retry the call, and if the error persists, contact the server administrator or Bitrix24 technical support
`500`	`ERROR_UNEXPECTED_ANSWER` Server returned an unexpected response	The server returned an unexpected response. Retry the call, and if the error persists, contact the server administrator or Bitrix24 technical support
`503`	`QUERY_LIMIT_EXCEEDED` Too many requests	The request intensity limit has been exceeded
`429`	`OPERATION_TIME_LIMIT` Method is blocked due to operation time limit	The method is blocked because the request resource intensity limit has been exceeded. The block is lifted automatically once the accumulated execution time of the method no longer exceeds the limit
`401`	`NO_AUTH_FOUND` Wrong authorization data	The request contains no authorization data: neither an access token nor a webhook code was passed
`401`	`INVALID_REQUEST` Https required	Methods are called over the HTTPS protocol only
`401`	`OVERLOAD_LIMIT` REST API is blocked due to overload	The REST API is blocked due to overload. This is a manual individual block. To have it lifted, contact Bitrix24 technical support
`401`	`ACCESS_DENIED` REST is available only on commercial plans	REST API access is not active for this account. In Bitrix24 Cloud, check the current plan or trial status: Vibe+ plans include REST API access, while Essentials plans do not. A webhook receives a different error message — `REST is available only by subscription`
`401`	`INVALID_CREDENTIALS` Invalid request credentials	No active webhook with the specified user identifier and secret code was found
`404`	`ERROR_METHOD_NOT_FOUND` Method not found!	No method with this name was found. The name is misspelled, the method does not exist in the REST API, or it is unavailable without the required scope
`401`	`insufficient_scope` The request requires higher privileges than provided by the webhook token	The request requires broader permissions than the token has: for a webhook these are the permissions granted to it, for an application it is the scope. For an application, the error message ends with `provided by the access token`
`401`	`expired_token` The access token provided has expired	The access token has expired
`401`	`user_access_error` The user does not have access to the application	The application is installed, but the Bitrix24 administrator has granted access to it only to specific users
`403`	`PORTAL_DELETED` Portal was deleted	The public part of the site is closed. To open it on an on-premise installation, disable the "Temporary closure of the public part of the site" option. Path to the setting: Desktop > Settings > Product Settings > Module Settings > Main Module > Temporary closure of the public part of the site

Continue Learning

Was the article helpful?

Submit Absence Report

Get Time Control Tool Settings

Get Report on Identified Absences timeman.timecontrol.reports.get

Method ParametersMethod Parameters

Code ExamplesCode Examples

Response HandlingResponse Handling

If the response has empty daysIf the response has empty days

Returned DataReturned Data

Objects daysObjects days

Objects reportsObjects reports

Object ip_networkObject ip_network

Object userObject user

Error HandlingError Handling

Possible Error CodesPossible Error Codes

Statuses and System Error CodesStatuses and System Error Codes

Continue LearningContinue Learning