Finding issues
Use this request to get a list of issues that meet specific criteria.
POST
https://api.tracker.yandex.net/v3/issues/_search?expand=transitions
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 a request, get permission to access the API.
To search for issues, use an HTTP POST
request. The request body contains the search criteria.
POST /v3/issues/_search?expand=transitions
Host: api.tracker.yandex.net
Authorization: OAuth <OAuth token>
X-Org-ID or X-Cloud-Org-ID: <organization_ID>
{
"filter": {
"<field_name>": "<field_value>"
},
"order":"+<field_key>"
}
Headers
-
Host
: Address of the node that provides the API. -
Authorization
: Authorization token about these formats:-
OAuth <OAuth_token>
: For authorization using the OAuth 2.0 protocol. Learn more -
Bearer <IAM_token>
: For authorization using an IAM token, if a Yandex Cloud Organization organization is linked to Tracker. Learn more
-
-
X-Org-ID
orX-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 and copy the value from the ID field.
-
Request parameters
Additional parameters
Parameter | Description | Data type |
---|---|---|
expand | Additional fields to include in the response:
|
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. Full list of issue fields | Map object |
query | Filter using the query language | String |
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 |
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 /v3/issues/_search?expand=attachments HTTP/1.1 Host: api.tracker.yandex.net Authorization: OAuth <OAuth token> X-Org-ID or X-Cloud-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 /v3/issues/_search?expand=attachments HTTP/1.1 Host: api.tracker.yandex.net Authorization: OAuth <OAuth token> X-Org-ID or X-Cloud-Org-ID: <organization_ID> { "query": "epic: notEmpty() Queue: TREK \"Sort by\": Updated DESC" }
Response format
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://api.tracker.yandex.net/v3/issues/TREK-9844",
"id": "593cd211ef7e8a33********",
"key": "TREK-9844",
"version": 7,
"lastCommentUpdatedAt": "2017-07-18T13:33:44.291+0000",
"summary": "subtask",
"parent": {
"self": "https://api.tracker.yandex.net/v3/issues/JUNE-2",
"id": "593cd0acef7e8a33********",
"key": "JUNE-2",
"display": "Task"
},
"aliases": [
"JUNE-3"
],
"updatedBy": {
"self": "https://api.tracker.yandex.net/v3/users/11********",
"id": "11********",
"display": "Ivan Ivanov"
},
"description": "<#<html><head></head><body><div>test</div><div> </div><div> </div> </body></html>#>",
"sprint": [
{
"self": "https://api.tracker.yandex.net/v3/sprints/53**",
"id": "53**",
"display": "sprint1"
}
],
"type": {
"self": "https://api.tracker.yandex.net/v3/issuetypes/2",
"id": "2",
"key": "task",
"display": "Issue"
},
"priority": {
"self": "https://api.tracker.yandex.net/v3/priorities/2",
"id": "2",
"key": "normal",
"display": "Normal"
},
"createdAt": "2017-06-11T05:16:01.339+0000",
"followers": [
{
"self": "https://api.tracker.yandex.net/v3/users/11********",
"id": "11********",
"display": "Ivan Ivanov"
}
],
"createdBy": {
"self": "https://api.tracker.yandex.net/v3/users/11********",
"id": "11********",
"display": "Ivan Ivanov"
},
"votes": 0,
"assignee": {
"self": "https://api.tracker.yandex.net/v3/users/11********",
"id": "11********",
"display": "Ivan Ivanov"
},
"project": {
"primary": {
"self": "https://api.tracker.yandex.net/v3/projects/1",
"id": "1",
"display": "Startrek project"
},
"secondary": []
},
"queue": {
"self": "https://api.tracker.yandex.net/v3/queues/TREK",
"id": "111",
"key": "TREK",
"display": "Startrek"
},
"updatedAt": "2017-07-18T13:33:44.291+0000",
"status": {
"self": "https://api.tracker.yandex.net/v3/statuses/1",
"id": "1",
"key": "open",
"display": "Open"
},
"previousStatus": {
"self": "https://api.tracker.yandex.net/v3/statuses/2",
"id": "2",
"key": "resolved",
"display": "Resolved"
},
"favorite": false
},
{...}
]
Response parameters
The table lists frequently used issue parameters. For a full list of supported parameters, see https://tracker.yandex.com/admin/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 |
version | Issue version. Changing issue parameters increases the issue's version number. Issue edits will be disabled if the version number reaches the threshold value of 10100 (for robots) or 11100 (for users) |
Number |
lastCommentUpdatedAt | Date and time when the last comment was added | String |
summary | Issue name | String |
parent | Object with information about the parent issue | Map object |
aliases | Array with information about alternative issue keys | Array of strings |
updatedBy | Object with information about the employee who edited the issue last | Map object |
description | Problem description | String |
sprint | Array of objects with information about the sprint | Array of objects |
type | Object with information about the issue type | Map object |
priority | Object with information about the priority | Map 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 | Map object |
votes | Number of votes for the issue | Number |
assignee | Object with information about the issue's assignee | Map object |
project | Object with information about the issue project | Map object |
queue | Object with information about the issue queue | Map object |
updatedAt | Date and time when the issue was last updated | String |
status | Object with information about the issue status | Map object |
previousStatus | Object with information about the previous status of the issue | Map object |
favorite | Favorite issue flag:
|
Boolean |
tags | Issue tags | Array of strings |
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 | 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 |
Sprint
array object fields
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 |
type
object fields
Parameter | Description | Data type |
---|---|---|
self | Address of the API resource with information about the issue type. | String |
id | Issue type ID | String |
key | Issue type key. | String |
display | Issue type name displayed. | String |
priority
object fields
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 | 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 |
createdBy
object fields
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 |
assignee
object fields
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 |
project
object fields
Parameter | Description | Data type |
---|---|---|
primary | Main issue project | Object |
secondary | List of additional issue projects | Array of objects |
If the request address specifies API v2
, the project
object contains information only about the main project.
Fields of the object that contains project data
The primary
and secondary
parameters contain objects with the following 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 is not authorized. Make sure that actions described in the API access section are performed.
- 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.
- 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.
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 is not used together with the
keys
orqueue
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 thefilter
orquery
parameters. -
perScroll
Maximum number of issues per response. The default value is 100. The maximum allowed value is 1,000.
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 60,000.
-
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. If an issue was edited and no longer meets the search criteria, it will still appear 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:
- An HTTP
POST
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
Example:
POST /v3/issues/_search?scrollType=sorted&perScroll=100&scrollTTLMillis=10000 Host: api.tracker.yandex.net Authorization: OAuth <OAuth_token> X-Org-ID or X-Cloud-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: <api.tracker.yandex.net/v3/issues/_search?expand=&embed=&fields=&staleOk=false&scrollType=sorted&scrollTTLMillis=10000&perScroll=2000>; rel="first" Link: <api.tracker.yandex.net/v3/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 isn't the last page in the list of search results, the following headers are also returned:
X-Scroll-Id
: The value is used in thescrollId
parameter to get the next results page.X-Scroll-Token
: This value is not used in the current v3 API version.
-
Create the second request of the sequence with the
scrollId
andscrollToken
parameters obtained in the previous step.Example:
POST /v3/issues/_search?scrollId=cXVlcnlU<...>&scrollTTLMillis=10000 Host: api.tracker.yandex.net Authorization: OAuth <OAuth_token> X-Org-ID or X-Cloud-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
andX-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.