---
metadata:
  - name: generator
    content: Diplodoc Platform v5.47.3
alternate:
  - https://yandex.com.tr/support/tracker/en/api-ref/entities/get-events-relative.md
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.com.tr/support/tracker/en/llms.txt

# Getting entity event history

The request allows you to get a paginated [entity](https://yandex.com.tr/support/tracker/en/api-ref/entities/about-entities.md) event history.

<div class="request_example method_get yfm-clipboard">
    <p>GET</p>
    <pre><code>https://api.tracker.yandex.net/v3/entities/&lt;entity_type>/&lt;entity_ID>/events/_relative</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/_assets/style/methods.md -->

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

## Query format {#query}

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

To get the paginated event history, use an HTTP `GET` request.

```json translate=no
GET /v3/entities/<entity_type>/<entity_ID>/events/_relative
Host: api.tracker.yandex.net
Authorization: OAuth <OAuth_token>
X-Org-ID or X-Cloud-Org-ID: <organization_ID>
```

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

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

* <!-- source: en/_includes/api/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 Cloud Organization organization is linked to Tracker. [Learn more](https://yandex.com.tr/support/tracker/en/api-ref/access.md#iam-token)
  <!-- endsource: en/_includes/api/authorization.md -->


* <!-- source: en/_includes/api/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 Cloud Organization.

  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/_includes/api/org-id.md -->


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

<!-- source: en/_includes/api/resource-entity.md -->
{% cut "Resource" %}

| Parameter | Description | Data type |
-------- | -------- | ----------
| \<entity_type> | Entity type:<ul><li>project</li><li>portfolio</li><li>goal</li></ul> | String |
| \<entity_ID> | Entity ID. To get the ID, see the [entity list](search-entities.md). You can use the `id` or `shortId` parameter as the ID. | String |

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

{% cut "Request parameters" %}

If no parameters are specified, the full list of events is displayed.

**Additional parameters**

#|
|| **Parameter** | **Description** | **Data type** ||
|| perPage | Sets the maximum number of events in the response. The default value is 50. | Number ||
|| from | ID of the event after which the list starts to be generated. The event itself is not included in the list. Not used together with the `selected` parameter. | String ||
|| selected | ID of the event around which the list is generated. Not specified together with the `from` parameter. The list is generated in the following order (for `perPage=5`):
1. Event with the specified ID.
2. Event that precedes the first event.
3. Event that follows the first event.
4. Event that precedes the second event.
5. Event that follows the third event. | String ||
|| newEventsOnTop | Reverses the order of events in the list. The default value is `false`. | Boolean ||
|| direction | Sets the order of events in the list:
* `forward` (default)
* `backward`: Inverts the `newEventsOnTop` parameter value | String ||
|#

{% endcut %}

> Example: Getting a list of events
>
> - An HTTP GET method is used.
> - The response displays information about three events.
> - The list starts with the event following `<event_1_ID>`.
>
> ```
> GET https://api.tracker.yandex.net/v3/entities/project/<project_ID>/events/_relative?perPage=3&from=<ID_of_event_1>
> ```

## Response format {#answer}

{% list tabs %}

- Request executed successfully

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

  The response body contains information about the entity events in JSON format.

  ```json translate=no
  {
      "events": [
          {
              "id": "65a26b254dbe6212********",
              "author": {
                  "self": "https://api.tracker.yandex.net/v3/users/11********",
                  "id": "11********",
                  "display": "User Name",
                  "cloudUid": "ajeppa7dgp71********",
                  "passportUid": 11********
              },
              "date": "2024-01-13T10:51:17.821+0000",
              "transport": "v3",
              "display": "Issue updated",
              "changes": [
                  {
                      "diff": "<added>User Name</added>",
                      "field": {
                          "id": "teamUsers",
                          "display": "Participants"
                      }
                  }
              ]
          },
          {
              "id": "65a26b264dbe6215********",
              "author": {
                  "self": "https://api.tracker.yandex.net/v3/users/11********",
                  "id": "11********",
                  "display": "User Name",
                  "cloudUid": "ajeppa7dgp71********",
                  "passportUid": 11********
              },
              "date": "2024-01-13T10:51:17.954+0000",
              "transport": "v3",
              "display": "Comment added",
              "changes": [
                  {
                      "diff": "<added>My comment</added>",
                      "field": {
                          "id": "comment.text",
                          "display": "Comment text",
                          "addedSummonees": [
                              {
                                  "self": "https://api.tracker.yandex.net/v3/users/11********",
                                  "id": "11********",
                                  "display": "User Name",
                                  "cloudUid": "ajeppa7dgp71********",
                                  "passportUid": 11********
                              }
                          ],
                          "email": null
                      },
                      "commentUrl": ""
                  }
              ]
          },
          {
              "id": "65a26b384dbe6216********",
              "author": {
                  "self": "https://api.tracker.yandex.net/v3/users/11********",
                  "id": "11********",
                  "display": "User Name",
                  "cloudUid": "ajeppa7dgp71********",
                  "passportUid": 11********
              },
              "date": "2024-01-13T10:51:36.807+0000",
              "transport": "v3",
              "display": "File added",
              "changes": [
                  {
                      "diff": "<added>Add a file</added>",
                      "field": {
                          "id": "comment.text",
                          "display": "Comment",
                          "email": null
                      },
                      "commentUrl": ""
                  },
                  {
                      "diff": "<added>image.jpg</added>",
                      "field": {
                          "id": "issue.attachments",
                          "display": "Attachments"
                      }
                  }
              ]
          }
      ],
      "hasNext": true,
      "hasPrev": true
  }
  ```

  {% cut "Response parameters" %}

  | Parameter | Description | Data type |
  ----- | ----- | -----
  | [events](#events) | Array of objects with information about the events | Array of objects |
  | hasNext | Indicates the presence of subsequent entries in the list. | Boolean |
  | hasPrev | Indicates the presence of previous entries in the list. | Boolean |

  `events` **array object fields** {#events}

  | Parameter | Description | Data type |
  ----- | ----- | -----
  | id | Event ID | String |
  | [author](#author) | Object with the event author information | Map object |
  | date | Event creation date and time in the format:<br/>```YYYY-MM-DDThh:mm:ss.sss±hhmm ``` | String |
  | transport | Service parameter | String |
  | display | Displayed event name | String |
  | changes | Array of objects with information about the changes. Composition and contents of object fields depend on the parameter you change. | Array of objects |

  `author` **object fields** {#author}

  <!-- source: en/_includes/api/user.md -->
  | Parameter | Description | Data type |
  ----- | ----- | -----
  | self | Address of the API resource with information about the user | String |
  | id | User ID. | String |
  | display | Displayed user name | String |
  | passportUid | Unique ID of the user account in the Yandex 360 for Business organization and Yandex ID. | Number |
  | cloudUid | Unique user ID in Yandex Cloud Organization | String |
  <!-- endsource: en/_includes/api/user.md -->

  {% endcut %}

- Request failed

  If the request is processed incorrectly, the API returns a response with an error code:

  <!-- source: en/_includes/api/answer-error-400.md -->
  400
  :   One or more request parameters have an invalid value.
  <!-- endsource: en/_includes/api/answer-error-400.md -->

  <!-- source: en/_includes/api/answer-error-404.md -->
  404
  :   The requested object was not found. You may have specified an invalid object ID or key.
  <!-- endsource: en/_includes/api/answer-error-404.md -->

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

{% endlist %}