---
metadata:
  - name: generator
    content: Diplodoc Platform v5.54.5
  - property: og:type
    content: article
  - property: article:section
    content: API reference
  - property: og:title
    content: Find employee absences
  - property: article:tag
    content: Technical instructions
alternate:
  - https://yandex.com.tr/support/tracker/en/api-ref/gaps/search-gaps.md
  - href: en/api-ref/gaps/search-gaps.md
    type: text/markdown
    title: Markdown version
  - href: ../../llms.txt
    type: text/markdown
    title: llms.txt
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.com.tr/support/tracker/en/llms.txt


# Find employee absences

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

<div class="request_example method_post yfm-clipboard">
    <p>POST</p>
    <pre><code>https://api.tracker.yandex.net/v3/gaps/_search</code></pre>
    <button class="yfm-clipboard-button"><svg width="16" height="16" viewBox="0 0 24 24" class="yfm-clipboard-icon" data-animation="15">
    <path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path>
    <path stroke="currentColor" fill="transparent" strokewidth="1.5" d="M9.5 13l3 3l5 -5" visibility="hidden">
        <animate id="visibileAnimation-15" attributeName="visibility" from="hidden" to="visible" dur="0.2s" fill="freeze" begin=""></animate>
        <animate id="hideAnimation-15" attributeName="visibility" from="visible" to="hidden" dur="1s" begin="visibileAnimation-15.end+1" fill="freeze"></animate>
    </path>
</svg>
</button>
</div>

<!-- source: en/api-ref/_assets/style/methods.md -->

<!-- endsource: en/api-ref/_assets/style/methods.md -->

## Request format {#query}

Before making the request, [get access to the API](https://yandex.com.tr/support/tracker/en/api-ref/access.md).

<!-- source: en/api-ref/_includes/query-admin.md -->
{% note info "" %}

You need [Administrator](https://yandex.com.tr/support/tracker/en/role-model.md#admin) rights to run this request.

{% endnote %}
<!-- endsource: en/api-ref/_includes/query-admin.md -->

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

```json translate=no
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>"
}
```

<!-- source: en/api-ref/_includes/headings.md -->
{% cut "Headers" %}

* `Host`: address of the node that provides the API.

* <!-- source: en/api-ref/_includes/authorization.md -->
  `Authorization`: Authorization token about these formats:

    - `OAuth <OAuth_token>`: For authorization using the OAuth 2.0 protocol. [Learn more](https://yandex.com.tr/support/tracker/en/api-ref/access.md#about_OAuth)

    - `Bearer <IAM_token>`: For authorization using an IAM token, if a Yandex Identity Hub organization is linked to Tracker. [Learn more](https://yandex.com.tr/support/tracker/en/api-ref/access.md#iam-token)
  <!-- endsource: en/api-ref/_includes/authorization.md -->


* <!-- source: en/api-ref/_includes/org-id.md -->
  `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**](https://tracker.yandex.com/admin/orgs) and copy the value from the **ID** field. {#find-id}
  <!-- endsource: en/api-ref/_includes/org-id.md -->


{% endcut %}
<!-- endsource: en/api-ref/_includes/headings.md -->

{% cut "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

{% endcut %}

{% cut "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

{% endcut %}

> 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.
>
> ```json translate=no
> 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 {#answer}

{% list tabs %}

- Request executed successfully

    <!-- source: en/api-ref/_includes/answer-200.md -->
    If the request is successful, the API returns a response with code `200 OK`.
    <!-- endsource: en/api-ref/_includes/answer-200.md -->

    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.

    ```json translate=no
    {
      "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
    }
    ```

    {% cut "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](#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** {#user}

    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

    {% endcut %}

- Request executed with error

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

    <!-- source: en/api-ref/_includes/answer-error-401.md -->
    401
    :   The user is not authorized. Make sure that actions described in the [API access](https://yandex.com.tr/support/tracker/en/api-ref/access.md) section are performed.
    <!-- endsource: en/api-ref/_includes/answer-error-401.md -->

    <!-- source: en/api-ref/_includes/answer-error-403.md -->
    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.
    <!-- endsource: en/api-ref/_includes/answer-error-403.md -->

    <!-- source: en/api-ref/_includes/answer-error-422.md -->
    422
    :   JSON validation error, the request is rejected.
    <!-- endsource: en/api-ref/_includes/answer-error-422.md -->

    {% note info "" %}

    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.

    {% endnote %}

{% endlist %}