Get Issue History

Use Case

Get a history of changes applied to a specific issue using the YouTrack REST API.

Summary

To read the change history for a specific issue, use the following resource:

/api/issues/{issueID}/activities

The collection of historical changes are accessible using a single GET request to this resource endpoint. To get exactly what you're looking for, pay careful attention to the parameters you add to the request:

category — this mandatory parameter filters for specific types of historical changes. This means that you need to specify at least one category for each request. For a list of supported categories, see ActivityCategory.
fields — as with any other request in YouTrack, this parameter lists the attributes that you want server to return in response. For issue history items, we recommend that you ask for the following attributes:
- author to see who applied the change.
- added to see what values were added to the issue.
- removed to see what values were removed from the issue.
The list of supported attributes differs based on the type of activity that you request with the categories parameter. For a list of supported activity items and their attributes, see ActivityItem.
{issue ID} represents the unique ID of the target issue. You can identify the issue by its entityID (for example, 2-32) or human-readable ID as you see it in the user interface (for example, SP-32).

As the entire issue history is accessible using a single quest, this use case doesn't require step-by-step instructions. The entire operation can be described with one sample request.

Sample Request

In this sample request, we instruct the server to read the change history for the issue 'SP-32' and return a list of changes that match the following categories:

CustomFieldCategory — the collection of changes applied to custom fields in the target issue.
CommentsCategory — changes applied to comments in this issue.

As for the attributes, let's request those that we recommended above: author, added, and removed. In addition, let's request the timestamp attribute so we know when these changes were applied. To get more data for the comment activity items, let's also specify the target(id,text) attribute. It will get you the comment IDs and text.

In the end, our fields parameter looks as follows:

fields=author(name,login),timestamp,target(id,text),added(name),removed(name)

Here's the complete request:

        curl -L -X GET 'https://example.youtrack.cloud/api/issues/SP-32/activities?categories=CustomFieldCategory,CommentsCategory&fields=author(name,login),timestamp,target(text),added(name),removed(name) \
        -H 'Accept: application/json' \
        -H 'Authorization: Bearer perm:am9obi5kb2U=.UG9zdG1hbiBKb2huIERvZQ==.jJe0eYhhkV271j1lCpfknNYOEakNk7'
      

In response, the server would return the following data:

        [
          {
            "added": [
              {
                "name": "Sprint 1",
                "$type": "VersionBundleElement"
              }
            ],
            "removed": [],
            "author": {
              "login": "jane.doe",
              "name": "Jane Doe",
              "$type": "User"
            },
            "timestamp": 1644916724088,
            "$type": "CustomFieldActivityItem"
          },
          {
            "author": {
              "login": "jane.doe",
              "name": "Jane Doe",
              "$type": "User"
            },
            "added": [
              {
                "$type": "IssueComment"
              }
            ],
            "removed": [],
            "timestamp": 1647869116494,
            "target": {
              "text": "made new tweaks according to the latest requirements -- @john.smith please verify",
              "id": "136-261",
              "$type": "IssueComment"
            },
            "$type": "CommentActivityItem"
          },
          {
            "added": [
              {
                "name": "Fixed",
                "$type": "StateBundleElement"
              }
            ],
            "removed": [
              {
                "name": "Open",
                "$type": "StateBundleElement"
              }
            ],
            "author": {
              "login": "jane.doe",
              "name": "Jane Doe",
              "$type": "User"
            },
            "timestamp": 1648110830229,
            "$type": "CustomFieldActivityItem"
          }
        ]
      

Last modified: 7 November 2024