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"
}
Request parameters
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.
Request message body
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:

  • transitions — Lifecycle transitions between statuses.
  • attachments — Attached files.

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:

  • transitions — Lifecycle transitions between statuses.
  • attachments — Attached files.

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
    },
    {...}
]
Response parameters
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:

  • true — The user added the issue to Favorites.

  • false — The issue is not in the user's Favorites.

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:

  • true — The user added the issue to Favorites.

  • false — The issue is not in the user's Favorites.

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 or queue. If you use these parameters together, the response will contain code 400 and the message Scroll 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.