Find employee absences

The request returns absence records for specified users that overlap with a specified time window. The results are grouped by user.

POST

https://api.tracker.yandex.net/v3/gaps/_search

Request format

Before making the request, get access to the API.

You need Administrator rights to run this request.

To find employee absence records, use an HTTP request with the POST method. In the request body, specify the parameters in JSON format.

POST /v3/gaps/_search?page=1&perPage=20
Host: api.tracker.yandex.net
Authorization: OAuth <OAuth-token>
Content-Type: application/json
X-Org-ID or X-Cloud-Org-ID: <organization_ID>

{
  "users": ["<user_login>"],
  "from": "<start_date>",
  "to": "<end_date>"
}
Headers

  • Host: address of the node that provides the API.

  • Authorization: Authorization token about these formats:

    • OAuth <OAuth_token>: For authorization using the OAuth 2.0 protocol. Learn more

    • Bearer <IAM_token>: For authorization using an IAM token, if a Yandex Identity Hub organization is linked to Tracker. Learn more

  • X-Org-ID or X-Cloud-Org-ID: Organization ID.

    • Use the X-Org-ID header if a Tracker organization is linked to Yandex 360 for Business.

    • Use the X-Cloud-Org-ID header if a Tracker organization is linked to Yandex Identity Hub.

    To get the organization ID, go to Administration → Organizations and copy the value from the ID field.

Request parameters

Additional parameters

Parameter Description Data type
page Page number for paginated output. The default value is 1 Number
perPage Number of users per response page. The default value is 50 Number
Request body parameters

Required parameters

Parameter Description Data type
users Logins or IDs of users to get absence records for. The maximum number is 100 Array of strings

Additional parameters

Parameter Description Data type
from Start of the search time window in ISO 8601 format. If the parameter is not specified, the current time is used String
to End of the search time window in ISO 8601 format. If specified, it must be strictly greater than from String

Example: Find the absences of two employees for July and August 2026

  • The HTTP POST method is used.
  • Searching for absences for users username1 (vacation in July) and username2 (business trip in August) for the period from July 1 to August 31, 2026.
  • The results are displayed on the first page, 20 users per page.
POST /v3/gaps/_search?page=1&perPage=20
Host: api.tracker.yandex.net
Authorization: OAuth y0__xAbc******
X-Org-ID: 1234******

{
 "users": ["username1", "username2"],
 "from": "2026-07-01T00:00:00.000Z",
 "to": "2026-08-31T23:59:59.999Z"
}

Response format

If the request is successful, the API returns a response with code 200 OK.

The response body contains the results in JSON format. Every requested user is present in the response; if they have no absences in the specified period, the gaps array will be empty.

{
  "userGaps": [
    {
      "user": {
        "self": "https://api.tracker.yandex.net/v3/users/1234567890123456",
        "uid": 1234567890123456,
        "login": "username1",
        "trackerUid": 1234567890123456,
        "passportUid": 1234567890,
        "cloudUid": "ajehs6sinuiii1234567",
        "firstName": "John",
        "lastName": "Smith",
        "display": "John Smith",
        "email": "username@example.com",
        "external": false,
        "dismissed": false,
        "firstLoginDate": "2024-01-10T10:15:47.272+0000",
        "lastLoginDate": "2026-07-23T08:11:01.861+0000",
        "sources": [
          "directory"
        ]
      },
      "gaps": [
        {
          "id": "68340a1f2b4c1a3d5e7f9011",
          "workflow": "vacation",
          "from": "2026-07-01T00:00:00.000+0000",
          "to": "2026-07-15T00:00:00.000+0000",
          "fullDay": true,
          "workInAbsence": false
        }
      ]
    },
    {
      "user": {
        "self": "https://api.tracker.yandex.net/v3/users/9876543210987654",
        "uid": 9876543210987654,
        "login": "username2",
        "trackerUid": 9876543210987654,
        "passportUid": 9876543210,
        "cloudUid": "ajehs6sinuiii9876543",
        "firstName": "John",
        "lastName": "Smith",
        "display": "Sam Brown",
        "email": "username@example.com",
        "external": false,
        "dismissed": false,
        "firstLoginDate": "2024-03-05T09:00:00.000+0000",
        "lastLoginDate": "2026-07-22T17:30:00.000+0000",
        "sources": [
          "directory"
        ]
      },
      "gaps": [
        {
          "id": "68340a1f2b4c1a3d5e7f9012",
          "workflow": "trip",
          "from": "2026-08-04T00:00:00.000+0000",
          "to": "2026-08-08T00:00:00.000+0000",
          "fullDay": true,
          "workInAbsence": false
        }
      ]
    }
  ],
  "hasMore": false
}
Response parameters
Parameter Description Data type
userGaps Array of absence records grouped by user. Contains one element for each requested user Array of objects
hasMore Flag indicating the presence of the next results page. The true value means there are more pages Boolean

Fields of the userGaps array objects

Parameter Description Data type
user Object with information about the user Object
gaps Array of user absence records in the specified period. Empty if there are no matches Array of objects

Fields of the user object

Parameter Description Data type
self Address of the API resource that contains user information String
uid Unique user ID Number
login User login String
trackerUid User ID in Tracker Number
passportUid Unique user account ID in Yandex ID Number
cloudUid Unique user ID in Yandex Identity Hub String
firstName User's first name String
lastName User's last name String
display User's display name String
email User's email address String
external Flag indicating an external user Boolean
dismissed Flag indicating a dismissed employee Boolean
firstLoginDate Date and time of the user's first login to the system String
lastLoginDate Date and time of the user's last login to the system String
sources User data sources. Possible values: directory — profile obtained from the organization's corporate directory; tracker — user added directly to Tracker Array of strings

Fields of the gaps array objects

Parameter Description Data type
id ID of the absence record String
workflow Type of absence. Possible values: vacation — vacation, paid_day_off — paid day off, illness — illness, absence — absence (general), trip — business trip, conference_trip — conference trip, conference — conference, learning — training, maternity — maternity leave, duty — on-duty. The current list is available via the GET /v3/gaps/workflows request String
from Start date and time of the absence in ISO 8601 format String
to End date and time of the absence in ISO 8601 format String
fullDay Flag indicating a full-day absence Boolean
workInAbsence Flag indicating working during the absence Boolean

If the request was not successfully processed, the API returns a response with an error code:

401
The user is not authorized. Make sure that actions described in the API access section are performed.
403
You are not authorized to perform this action. You can check what rights you have in the Tracker interface. The same rights are required to perform an action via the API and interface.
422
JSON validation error, the request is rejected.

The 422 code is returned in the following cases:

  • The users array is empty.
  • The number of elements in the users array exceeds 100.
  • The from value is greater than or equal to to.
  • One of the specified users is not found.
Previous
Create absences
Next
Delete absences