Find issues
Use this request to get a list of issues that meet specific criteria. If there are more than 10,000 issues in the response, use paging.
Request format
To search for issues, use an HTTP POST
request: The request body contains the search criteria.
POST /v2/issues/_search?
order=<sort direction>
&expand=<additional fields in response>
Host: https://api.tracker.yandex.net
Authorization: OAuth <OAuth token>
X-Org-Id: <organization ID>
{
"filter": {
"<field name>": "<field value>"
}
"query": "filter query",
"expand": "additional fields"
"keys": "list of issue keys"
"queue": "queue key"
}
- order (optional)
-
The direction and field for sorting issues. The value is specified in the format
[+/-]<field name>
. Use the + or - sign to indicate the sort direction. - expand (optional)
-
Additional fields to include in the response:
transitions
— Workflow transitions between statuses.attachments
— Attached files.
transitions
— Lifecycle transitions between statuses.attachments
— Attached files.transitions
— Lifecycle transitions between statuses.attachments
— Attached files.
Parameter | Description | Format |
---|---|---|
filter | Parameters for filtering issues. The parameter can specify any field and value to filter by. | Object |
query | A filter using the query language. | String |
expand | Additional fields to include in the response: | String |
keys | A list of queue keys. This parameter is not used with the filter or query parameters. If you pass these parameters together, only keys will be searched. | String |
queue | Queue. This parameter is not used with the filter or query parameters. If you pass these parameters together, only queue will be searched. | String |
Parameter | Description | Format |
---|---|---|
filter | Parameters for filtering issues. The parameter can specify any field and value to filter by. | Object |
query | A filter using the query language. | String |
expand | Additional fields to include in the response: | String |
keys | A list of queue keys. This parameter is not used with the filter or query parameters. If you pass these parameters together, only keys will be searched. | String |
queue | Queue. This parameter is not used with the filter or query parameters. If you pass these parameters together, only queue will be searched. | String |
The queue
and keys
parameters can't be used simultaneously with the filter
and query
parameters. If they are passed together, the response will contain the code 400 with the message You can only use keys, queue or search request.
Request for a list of issues with additional filtering options:
Uses the HTTP POST method.
Paginated results are enabled, and each page contains two entries.
The response will display attachments.
The response should only contain tasks from the “JUNE” queue that don't have an assignee.
POST /v2/issues/_search?scrollType=sorted&perScroll=2&expand=attachments HTTP/1.1
Host: https://api.tracker.yandex.net
Authorization: OAuth <OAuth token>
X-Org-Id: <organization ID>
Cache-Control: no-cache
{
"filter": {
"queue": "JUNE",
"assignee": "Empty()"
}
}
Response format
[
{
"self": "https://api.tracker.yandex.net/v2/issues/TREK-9844",
"id": "593cd211ef7e8a332414f2a7",
"key": "TREK-9844",
"version": 7,
"lastCommentUpdatedAt": "2017-07-18T13:33:44.291+0000",
"summary": "subtask",
"parent": {
"self": "https://api.tracker.yandex.net/v2/issues/JUNE-2",
"id": "593cd0acef7e8a332414f28e",
"key": "JUNE-2",
"display": "Task"
},
"aliases": [
"JUNE-3"
],
"updatedBy": {
"self": "https://api.tracker.yandex.net/v2/users/1120000000016876",
"id": "<user ID>",
"display": "<user's display name>"
},
"description": "<#<html><head></head><body><div>test</div><div> </div><div> </div> </body></html>#>",
"sprint": [
{
"self": "https://api.tracker.yandex.net/v2/sprints/5317",
"id": "5317",
"display": "sprint1"
}
],
"type": {
"self": "https://api.tracker.yandex.net/v2/issuetypes/2",
"id": "2",
"key": "task",
"display": "Issue"
},
"priority": {
"self": "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://api.tracker.yandex.net/v2/users/1120000000016876",
"id": "<user ID>",
"display": "<user's display name>"
}
],
"createdBy": {
"self": "https://api.tracker.yandex.net/v2/users/1120000000049224",
"id": "<user ID>",
"display": "<user's display name>"
},
"votes": 0,
"assignee": {
"self": "https://api.tracker.yandex.net/v2/users/1120000000049224",
"id": "<user ID>",
"display": "<user's display name>"
},
"queue": {
"self": "https://api.tracker.yandex.net/v2/queues/TREK",
"id": "111",
"key": "TREK",
"display": "Tracker"
},
"updatedAt": "2017-07-18T13:33:44.291+0000",
"status": {
"self": "https://api.tracker.yandex.net/v2/statuses/1",
"id": "1",
"key": "open",
"display": "Open"
},
"previousStatus": {
"self": "https://api.tracker.yandex.net/v2/statuses/2",
"id": "2",
"key": "resolved",
"display": "Resolved"
},
"favorite": false
},
{...}
]
true
— The user added the issue to Favorites.false
— The issue is not in the user's Favorites.true
— The user added the issue to Favorites.false
— The issue is not in the user's Favorites.
Parameter | Description | Data type |
---|---|---|
self | URL of the API resource that contains information about the issue. | String. |
id | The issue ID. | String. |
key | The issue key. | String |
version | Version of the issue. Each change to the issue parameters increases the version number. | Integer. |
lastCommentUpdatedAt | The date and time when the last comment was added. | String. |
summary | Title of the issue. | String. |
parent | Object with information about the parent issue. | Object. |
aliases | Array with information about alternate issue keys. | Array of strings. |
updatedBy | Object with information about the last person who modified the issue. | Object. |
description | Description of the issue. | String. |
sprint | An array of objects with information about the sprint. | Array of objects. |
type | Object with information about the type of issue. | Object. |
priority | Object with information about the priority. | Object. |
createdAt | Date and time the issue was created. | String. |
followers | An array of objects with information about followers of the issue. | Array of objects. |
createdBy | Object with information about the person who created the issue. | Object. |
votes | Number of votes for the issue. | Integer. |
assignee | Object with information about the person assigned to the issue. | Object. |
queue | Object with information about the queue that the issue belongs to. | Object. |
updatedAt | Date and time when the issue was last updated. | String. |
status | Object with information about the status of the issue. | Object. |
previousStatus | Object with information about the previous status of the issue. | Object. |
favorite | Whether the issue is a favorite: | Boolean. |
Fields for the parent object | ||
self | Reference to the issue. | String. |
id | The issue ID. | String. |
key | The issue key. | String. |
display | The display name of the issue. | String. |
Fields for the updatedBy object | ||
self | Reference to the Tracker user. | String. |
id | User ID. | String. |
display | Display name of the user. | String. |
Fields for objects in the sprint array | ||
self | Reference to the sprint. | String. |
id | ID of the sprint. | String. |
display | Display name of the sprint. | String. |
Fields for the type object | ||
self | Reference to the type of issue. | String. |
id | ID of the issue type. | String. |
key | Key of the issue type. | String. |
display | Display name of the issue type. | String. |
Fields for the priority object | ||
self | Reference to the priority type. | String. |
id | Priority ID. | String. |
key | Priority key. | String. |
display | Display name of the priority. | String. |
Fields for objects in the followers array | ||
self | Reference to the Tracker user. | String. |
id | User ID. | String. |
display | Display name of the user. | String. |
Fields for the createdBy object | ||
self | Reference to the Tracker user. | String. |
id | User ID. | String. |
display | Display name of the user. | String. |
Fields for the assignee object | ||
self | Reference to the Tracker user. | String. |
id | User ID. | String. |
display | Display name of the user. | String. |
Fields for the queue object | ||
self | Reference to the queue. | String. |
id | The queue ID. | String. |
key | The queue key. | String. |
display | Display name of the queue. | String. |
Fields for the status object | ||
self | A reference to the status. | String. |
id | The status ID. | String. |
key | The status key. | String. |
display | Display name of the status. | String. |
Fields for the previousStatus object | ||
self | A reference to the status. | String. |
id | The status ID. | String. |
key | The status key. | String. |
display | Display name of the status. | String. |
Parameter | Description | Data type |
---|---|---|
self | URL of the API resource that contains information about the issue. | String. |
id | The issue ID. | String. |
key | The issue key. | String |
version | Version of the issue. Each change to the issue parameters increases the version number. | Integer. |
lastCommentUpdatedAt | The date and time when the last comment was added. | String. |
summary | Title of the issue. | String. |
parent | Object with information about the parent issue. | Object. |
aliases | Array with information about alternate issue keys. | Array of strings. |
updatedBy | Object with information about the last person who modified the issue. | Object. |
description | Description of the issue. | String. |
sprint | An array of objects with information about the sprint. | Array of objects. |
type | Object with information about the type of issue. | Object. |
priority | Object with information about the priority. | Object. |
createdAt | Date and time the issue was created. | String. |
followers | An array of objects with information about followers of the issue. | Array of objects. |
createdBy | Object with information about the person who created the issue. | Object. |
votes | Number of votes for the issue. | Integer. |
assignee | Object with information about the person assigned to the issue. | Object. |
queue | Object with information about the queue that the issue belongs to. | Object. |
updatedAt | Date and time when the issue was last updated. | String. |
status | Object with information about the status of the issue. | Object. |
previousStatus | Object with information about the previous status of the issue. | Object. |
favorite | Whether the issue is a favorite: | Boolean. |
Fields for the parent object | ||
self | Reference to the issue. | String. |
id | The issue ID. | String. |
key | The issue key. | String. |
display | The display name of the issue. | String. |
Fields for the updatedBy object | ||
self | Reference to the Tracker user. | String. |
id | User ID. | String. |
display | Display name of the user. | String. |
Fields for objects in the sprint array | ||
self | Reference to the sprint. | String. |
id | ID of the sprint. | String. |
display | Display name of the sprint. | String. |
Fields for the type object | ||
self | Reference to the type of issue. | String. |
id | ID of the issue type. | String. |
key | Key of the issue type. | String. |
display | Display name of the issue type. | String. |
Fields for the priority object | ||
self | Reference to the priority type. | String. |
id | Priority ID. | String. |
key | Priority key. | String. |
display | Display name of the priority. | String. |
Fields for objects in the followers array | ||
self | Reference to the Tracker user. | String. |
id | User ID. | String. |
display | Display name of the user. | String. |
Fields for the createdBy object | ||
self | Reference to the Tracker user. | String. |
id | User ID. | String. |
display | Display name of the user. | String. |
Fields for the assignee object | ||
self | Reference to the Tracker user. | String. |
id | User ID. | String. |
display | Display name of the user. | String. |
Fields for the queue object | ||
self | Reference to the queue. | String. |
id | The queue ID. | String. |
key | The queue key. | String. |
display | Display name of the queue. | String. |
Fields for the status object | ||
self | A reference to the status. | String. |
id | The status ID. | String. |
key | The status key. | String. |
display | Display name of the status. | String. |
Fields for the previousStatus object | ||
self | A reference to the status. | String. |
id | The status ID. | String. |
key | The status key. | String. |
display | Display name of the status. | String. |
Paginated results
If more than 10,000 issues meet the query criteria, you will need to use the scrolling mechanism to view the results page by page.
There are two ways to scroll through the pages — scrolling with the sorting specified in the request, and scrolling without using sorting. In the second case, the search results are returned in random order. Scrolling without sorting is more efficient when you receive a large number of issues.
- Scrolling without sorting
-
For scrolling without sorting, the request uses the following parameters:
- perPage (optional)
-
Number of tickets per page. The default value is 50 and the maximum value is 100.
- page (optional)
-
The page number of the response. The default is 1.
The response will contain the following headers:
- X-Total-Pages
- Total number of pages with records.
- X-Total-Count
- The total number of records in the response.
This method calculates the results each time a new page is displayed. This means that if there are changes in the results while you are viewing a single page, this may affect how the following pages are displayed. For example, the request found 11 issues, 10 of which are displayed. While you were viewing the results of the first page, one of the issues was changed and no longer meets the request criteria. In this case, when the second page of results is requested, an empty array is returned, since the remaining 10 tasks are on the first page.
- Scrolling using sorting
-
For scrolling with sorting, use the following parameters in the request:
- scrollType
- The type of scrolling. Possible values:
sorted
— Uses the sorting specified in the request.unsorted
— Sorting is not used.
This parameter is not used simultaneously with the parameters
keys
orqueue
. If you use these parameters together, the response will contain code 400 and the messageScroll is not supported
. - perScroll
- The maximum number of issues in the response. The default value is 5,000 and the maximum value is 10,000.
- scrollTTLMillis (optional)
- The TTL of the scrolling context in milliseconds. The default value is 5,000 and the maximum value is 5,000.
- scrollId
- The ID of the page. This parameter is specified starting from the second in a series of requests. The value of the ID is taken from the
X-Scroll-Id
header in the response to the previous search request. - scrollToken
- A token that identifies the request as belonging to the current user. The value of the ID is taken from the
X-Scroll-Token
header in the response to the previous search query.
The response will contain the following headers:
- Link
- The link to go to the next page of search results.
- X-Scroll-Id
-
The ID of the page.
- X-Scroll-Token
- A token that identifies the request as belonging to the current user.
- X-Total-Count
- The total number of records in the response.
This method creates a snapshot of search results, and pagination occurs within this snapshot. This means that if any issue is changed and no longer meets the search criteria in the request, it will not affect how the issue is displayed in the snapshot of search results. This method is more resource-intensive. The search snapshot is saved until all the pages with search results have been viewed. If you plan to stop viewing the search results before reaching the end, you must explicitly release the resources by using the Release scroll view resources request.
Possible response codes
- 200
- The request was successful.