Finding issues

Written by

Yandex Cloud

Updated at October 4, 2024

Request format
Response format
Scrollable search results

Use this request to get a list of issues that meet specific criteria.

If the number of rows in the response is less than 10,000, use paginated output.

If the number of rows in the response exceeds 10,000, use scrollable results.

Request format

Before making the request, get permission to access the API.

To search for issues, use an HTTP POST request. The request body contains the search criteria.

POST /v2/issues/_search?expand=transitions
Host: https://api.tracker.yandex.net
Authorization: OAuth <OAuth token
X-Org-ID: <organization ID>

{
   "filter": {
      "<field_name>": "<field_value>"
   },
   "order":"+<field_key>"
}

Headers

Host

Address of the node that provides the API:
```
https://api.tracker.yandex.net
```
Authorization

OAuth token in OAuth <OAuth_token> format, e.g.:
```
OAuth 0c4181a7c2cf4521964a72ff********
```
X-Org-ID or X-Cloud-Org-ID

Organization ID. You can find it out on the Tracker organizations page.
- If a Yandex 360 for Business organization is the only one linked to Tracker, the X-Org-ID header is used.
- If a Yandex Cloud Organization organization is the only one linked to Tracker, the X-Cloud-Org-ID header is used.
- If both Yandex 360 for Business and Yandex Cloud Organization organizations are linked to Tracker at the same time, the X-Org-ID header and the Yandex 360 for Business organization ID are used.

Request parameters

Additional parameters

Parameter	Description	Data type
expand	Additional fields to include in the response: `transitions`: Workflow transitions between statuses `attachments`: Attached files	String
perPage	Number of issues per response page. The default value is 50. To set up additional response output parameters, use pagination.	Number

Request body parameters

To get the issue list, specify one of the following parameters:

Parameter	Description	Format
queue	Queue	String
keys	List of issue keys	String or Array of strings
filter	Issue filtering parameters. The parameter can specify any field and value to filter by.	Object
query	Filter using the query language	String

Note

Do not combine parameters in your request.

If a combination of two parameters is used, the result will be returned for the higher priority parameter.
Parameter priorities (in descending order):

queue
keys
filter
query

If a combination of two or three parameters is used, the response will contain code 400 with a message saying You can only use keys, a queue, or a search query.

Additional parameters

Parameter	Description	Format
order	Issue sorting direction and field (only if combined with the `filter` parameter). The value is specified in `[+/-]<field_key>` format. Use the `+` or `-` sign to indicate the sorting direction.	String

Note

If the query parameter is used, specify the sorting method based on the query language.
Responses to requests with the queue parameter are sorted by issue key, and those to requests with the keys parameter by issue name in alphabetical order.

Example 1: Requesting an issue list using a filter:

An HTTP POST method is used.

The response will display attachments.

The response should only contain issues from the TREK queue with no assignee.

The results are sorted by status in ascending order.
POST /v2/issues/_search?expand=attachments HTTP/1.1
Host: https://api.tracker.yandex.net
Authorization: OAuth <OAuth token>
X-Org-ID: <organization ID>

{
  "filter": {
    "queue": "TREK",
    "assignee": "Empty()"
  },
  "order":"+status"
}

Example 1: Requesting an issue list using the query language:

An HTTP POST method is used.

The response should only contain issues from the TREK queue that are not epics.

The results are sorted by update date in descending order.
POST /v2/issues/_search?expand=attachments HTTP/1.1
Host: https://api.tracker.yandex.net
Authorization: OAuth <OAuth token>
X-Org-ID: <organization ID>

{
  "query": "epic: notEmpty() Queue: TREK \"Sort by\": Updated DESC",
}

Response format

Request executed successfully

Request failed

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

The response body contains the results in JSON format.

[
    {
    "self": "https://https://api.tracker.yandex.net/v2/issues/TREK-9844",
    "id": "593cd211ef7e8a33********",
    "key": "TREK-9844",
    "version": 7,
    "lastCommentUpdatedAt": "2017-07-18T13:33:44.291+0000",
    "summary": "subtask",
    "parent": {
        "self": "https://https://api.tracker.yandex.net/v2/issues/JUNE-2",
        "id": "593cd0acef7e8a33********",
        "key": "JUNE-2",
        "display": "Task"
        },
    "aliases": [
            "JUNE-3"
        ],

    "updatedBy": {
        "self": "https://https://api.tracker.yandex.net/v2/users/11********",
        "id": "11********",
        "display": "Ivan Ivanov"
        },
    "description": "<#<html><head></head><body><div>test</div><div>&nbsp;</div><div>&nbsp;</div> </body></html>#>",
    "sprint": [
            {
        "self": "https://https://api.tracker.yandex.net/v2/sprints/53**",
        "id": "53**",
        "display": "sprint1"
            }
        ],
    "type": {
        "self": "https://https://api.tracker.yandex.net/v2/issuetypes/2",
        "id": "2",
        "key": "task",
        "display": "Issue"
        },
    "priority": {
        "self": "https://https://api.tracker.yandex.net/v2/priorities/2",
        "id": "2",
        "key": "normal",
        "display": "Normal"
        },

    "createdAt": "2017-06-11T05:16:01.339+0000",
    "followers": [
        {
        "self": "https://https://api.tracker.yandex.net/v2/users/11********",
        "id": "11********",
        "display": "Ivan Ivanov"
        }
        ],
    "createdBy": {
        "self": "https://https://api.tracker.yandex.net/v2/users/11********",
        "id": "11********",
        "display": "Ivan Ivanov"
        },
    "votes": 0,
    "assignee": {
        "self": "https://https://api.tracker.yandex.net/v2/users/11********",
        "id": "11********",
        "display": "Ivan Ivanov"
        },
    "project": {
        "display": "Startrek project",
        "id": "1",
        "self": "https://https://api.tracker.yandex.net/v2/projects/1"
    },
    "queue": {
        "self": "https://https://api.tracker.yandex.net/v2/queues/TREK",
        "id": "111",
        "key": "TREK",
        "display": "Startrek"
        },
    "updatedAt": "2017-07-18T13:33:44.291+0000",
    "status": {
        "self": "https://https://api.tracker.yandex.net/v2/statuses/1",
        "id": "1",
        "key": "open",
        "display": "Open"
        },
    "previousStatus": {
        "self": "https://https://api.tracker.yandex.net/v2/statuses/2",
        "id": "2",
        "key": "resolved",
        "display": "Resolved"
        },
    "favorite": false
    },
    {...}
]

Response parameters

Parameter	Description	Data type
self	Address of the API resource with information about the issue.	String
id	Issue ID.	String
key	Issue key.	String
version	Issue version. Each change to the issue parameters increases its version number.	Number
lastCommentUpdatedAt	Date and time when the last comment was added.	String
summary	Issue name.	String
parent	Object with information about the parent issue.	Object
aliases	Array with information about alternative issue keys.	Array of strings
updatedBy	Object with information about the employee who edited the issue last.	Object
description	Issue description.	String
sprint	Array of objects with information about the sprint.	Array of objects
type	Object with information about the issue type.	Object
priority	Object with information about the priority.	Object
createdAt	Issue creation date and time.	String
followers	Array of objects with information about issue followers.	Array of objects
createdBy	Object with information about the user who created the issue.	Object
votes	Number of votes for the issue.	Number
assignee	Object with information about the issue's assignee.	Object
project	Object with information about the issue project.	Object
queue	Object with information about the issue queue.	Object
updatedAt	Date and time when the issue was last updated.	String
status	Object with information about the issue status.	Object
previousStatus	Object with information about the previous status of the issue.	Object
favorite	Favorite issue flag: `true`: Issue added to favorites by the user. `false`: Issue not added to favorites.	Logical

parent object fields

Parameter	Description	Data type
self	Address of the API resource with information about the issue.	String
id	Issue ID.	String
key	Issue key.	String
display	Issue name displayed.	String

updatedBy object fields

Parameter	Description	Data type
self	Address of the API resource with information about the user.	String
id	User ID.	String
display	User's name displayed.	String

Array object fields sprint

Parameter	Description	Data type
self	Address of the API resource with information about the sprint.	String
id	Sprint ID.	String
display	Sprint name displayed.	String

Object fields type

Parameter	Description	Data type
self	Address of the API resource with information about the issue type.	String
id	ID of the issue type.	String
key	Key of the issue type.	String
display	Issue type name displayed.	String

Object fields priority

Parameter	Description	Data type
self	Address of the API resource with information about the priority.	String
id	Priority ID.	String
key	Priority key.	String
display	Priority name displayed.	String

followers array object fields

Parameter	Description	Data type
self	Address of the API resource with information about the user.	String
id	User ID.	String
display	User's name displayed.	String

createdBy object fields

Parameter	Description	Data type
self	Address of the API resource with information about the user.	String
id	User ID.	String
display	User's name displayed.	String

assignee object fields

Parameter	Description	Data type
self	Address of the API resource with information about the user.	String
id	User ID.	String
display	User's name displayed.	String

project object fields

Parameter	Description	Data type
self	Address of the API resource with information about the project	String
id	Project ID	String
display	Project name displayed	String

queue object fields

Parameter	Description	Data type
self	Address of the API resource with information about the queue.	String
id	Queue ID.	String
key	Queue key.	String
display	Queue name displayed.	String

status object fields

Parameter	Description	Data type
self	Address of the API resource with information about the status.	String
id	Status ID.	String
key	Status key.	String
display	Status name displayed.	String

previousStatus object fields

Parameter	Description	Data type
self	Address of the API resource with information about the status.	String
id	Status ID.	String
key	Status key.	String
display	Status name displayed.	String

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

400: One or more request parameters have an invalid value.

401: The user isn't authorized. Make sure to perform the actions described in API access.

403: Insufficient rights 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.

404: The requested object was not found. You may have specified an invalid object ID or key.

Scrollable search results

If your issue search response includes more than 10,000 rows, we recommend scrollable results.

If using scrollable results, in response to your request you will get a page with search results and an ID to get the next page.

Search results can be ordered or displayed at random. To save on resources when retrieving numerous issues, use unsorted scrollable results.

Note

Scrollable search results consume more resources than paginated output.

Parameters of requests with scrollable results

scrollType

Scrolling type. Acceptable values include:
- sorted: Use sorting specified in the request.
- unsorted: No sorting.
This parameter is only used in the first request of the scrollable sequence.

This parameter isn't used together with the keys or queue search parameters. If you try to run a scrollable request with these parameters, the response will include code 400 and the message: Scroll is not supported. To find issues in the queue, use the filter or query parameters.
perScroll

Maximum number of issues per response. The default value is 100. The maximum allowed value is 1000.

This parameter is only used in the first request of the scrollable sequence.
scrollTTLMillis (optional parameter)

Scroll context lifetime in milliseconds. The default value is 60000.
scrollId

Page ID.

This parameter is only specified in the second and following requests of the scrollable sequence. The parameter value must be obtained from the X-inScroll-Id header returned in response to the previous request of the sequence.

Response to a scrollable request

A scrollable request creates a snapshot of search results. You can switch between the results pages within the snapshot. Thus if an issue was edited and no longer meets the search query criteria, it will not affect its output in the search results snapshot.

The snapshot of search results is preserved until all the pages have been viewed. If you do not want to load all the search results, clean busy resources using the Releasing scroll view resources request.

The response includes the headers:

Link

Link to the next search results page. You can only use the link to go to the next or first page.
X-Scroll-Id

Page ID.
X-Scroll-Token

Token that certifies that the request belongs to the current user.
X-Total-Count

Total number of entries in the response.

Example

Let's consider an example of using scrollable search results: finding all issues assigned to an employee.

Request conditions:

HTTP GET method is used.
Queue key: TREK.
Assignee: <user_login>.
Search results must be sorted.

Sequence of request execution:

Create the first request of the sequence with the parameters:

scrollType=sorted
perScroll=100
scrollTTLMillis=10000

For example:

POST /v2/issues/_search?scrollType=sorted&perScroll=100&scrollTTLMillis=10000
Host: https://api.tracker.yandex.net
Authorization: OAuth <OAuth_token>
X-Org-ID: <organization ID>

{
  "filter": {
    "queue": "TREK",
    "assignee": "<user_login>"
  }
}

The response will include a list of issues and the headers:

Link: URLs of the first and next result pages:

Link: <https://https://api.tracker.yandex.net/v2/issues/_search?expand=&embed=&fields=&staleOk=false&scrollType=sorted&scrollTTLMillis=10000&perScroll=2000>; rel="first"
Link: <https://https://api.tracker.yandex.net/v2/issues/_search?expand=&embed=&fields=&staleOk=false&scrollTTLMillis=10000&scrollId=6554d4cbbda0de18********&scrollToken=dummy-token-you-dont-have-to-specify-it>; rel="next"

Use the URL from the header with the rel="next" parameter to get the next results page.

X-Total-Count: Total number of issues in the output.

If the requested page is not the last one, the following headers will also be returned:

X-Scroll-Id. The value is used in the scrollId parameter to get the next results page.
X-Scroll-Token. This value is not used in the current v2 API version.

Create the second request of the sequence with the scrollId and scrollToken parameters obtained in the previous step.

For example:

POST /v2/issues/_search?scrollId=cXVlcnlU<...>&scrollTTLMillis=10000
Host: https://api.tracker.yandex.net
Authorization: OAuth <OAuth_token>
X-Org-ID: <organization ID>

{
  "filter": {
    "queue": "TREK",
    "assignee": "<user_login>"
  }
}

In response you will get the next page of the issue list and the next X-Scroll-Id and X-Scroll-Token values (if the page is not the last one).

Continue requesting the next results page until you get all the issues from the output.

Finding issues

Request formatRequest format

Response formatResponse format

Scrollable search resultsScrollable search results

Parameters of requests with scrollable resultsParameters of requests with scrollable results

Response to a scrollable requestResponse to a scrollable request

ExampleExample

Was the article helpful?

Request format

Response format

Scrollable search results

Parameters of requests with scrollable results

Response to a scrollable request

Example