Developer Portal for YouTrack and Hub 2021.3 Help

Get Issue History

This use case shows you how to 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.

    • added 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 attributes, let's request those that we recommended above. We'll specify the author, added, and removed attributes, plus the timestamp attribute so we know when these changes were applied. In the end, our fields parameter looks as follows:

fields=author(name,login),timestamp,added(name,login),removed(name,login)

Here's the complete request:

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

In response, the server would return the following data:

[ { "target": { "id": "2-31", "$type": "Issue" }, "removed": [], "added": [], "author": { "login": "john.doe", "name": "John Doe", "$type": "User" }, "timestamp": 1533139032010, "$type": "IssueCreatedActivityItem" }, { "removed": [], "added": [ { "$type": "IssueComment" } ], "author": { "login": "jane.doe", "name": "Jane Doe", "$type": "User" }, "timestamp": 1533214812208, "target": { "text": "@john.doe let's update the summary and description", "id": "4-0", "$type": "IssueComment" }, "$type": "CommentActivityItem" }, { "removed": [], "added": [ { "$type": "IssueComment" } ], "author": { "login": "john.doe", "name": "John Doe", "$type": "User" }, "timestamp": 1533221614364, "target": { "text": "okay, let's do it, @jane.doe. By the way, I'm updating this comment using REST.", "id": "4-2", "$type": "IssueComment" }, "$type": "CommentActivityItem" }, { "removed": [], "added": [ { "name": "Sample Project Team", "$type": "UserGroup" } ], "author": { "login": "john.doe", "name": "John Doe", "$type": "User" }, "timestamp": 1535649875680, "target": { "id": "2-31", "$type": "Issue" }, "$type": "VisibilityGroupActivityItem" } ]
Last modified: 13 July 2021