Searching dashboards

Use this request to return dashboards the user can access. You can filter the results by name and owner.

POST

https://api.tracker.yandex.net/v3/dashboards/_search

Request format

Before making a request, get permission to access the API. Pass search parameters in the JSON request body.

POST /v3/dashboards/_search
Host: api.tracker.yandex.net
Authorization: OAuth API_TOKEN
Content-Type: application/json
X-Org-ID or X-Cloud-Org-ID: ORGANIZATION_ID

{
  "name": "Team plans",
  "owner": {"login": "user-login"}
}

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 Identity Hub organization is linked to Tracker. Learn more
ID types

X-Org-ID or X-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 Identity Hub.
Finding the ID

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
perPage	Maximum number of dashboards per response page. Default: 50. The API reduces values above 500 to 500.	Number
id	ID of the last dashboard on the previous page. Pass it to get the next page.	Number

Request body parameters

Parameter	Description	Data type
name	Part of the dashboard name to search for.	String
owner	Dashboard owner. Pass an object with `login`, `id`, or another supported user identifier.	Object

Pagination mechanism

The request uses relative pagination. Results are sorted by id in descending order, with newer dashboards first. The id parameter returns dashboards with IDs less than the specified value. Set the page size with the perPage parameter; the default is 50. The maximum is 500 dashboards; the API reduces larger values to 500.

To get the first page, make the request without the id parameter.
To get the next page, pass the ID of the last dashboard from the previous response in id. Keep the same perPage value and search parameters in the request body.
Repeat requests with the new id while the Link header contains a rel="next" URL.

If the Link header contains a rel="next" URL, you can use it for the next request with the same body. If this URL is absent, you have reached the last page.

The X-Total-Count header contains the total number of matching dashboards; X-Total-Pages contains the number of pages for the selected page size.

Example of sequential requests

Get the first page:

POST /v3/dashboards/_search?perPage=20
Host: api.tracker.yandex.net
Authorization: OAuth API_TOKEN
Content-Type: application/json
X-Org-ID or X-Cloud-Org-ID: ORGANIZATION_ID

{
  "name": "Team plans"
}

Replace LAST_DASHBOARD_ID with the ID of the last dashboard from the response and request the next page:

POST /v3/dashboards/_search?perPage=20&id=LAST_DASHBOARD_ID
Host: api.tracker.yandex.net
Authorization: OAuth API_TOKEN
Content-Type: application/json
X-Org-ID or X-Cloud-Org-ID: ORGANIZATION_ID

{
  "name": "Team plans"
}

Response format

Request executed successfully

Request failed

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

On success, the API returns an array of dashboards and pagination headers.

[
  {
    "id": 123,
    "self": "https://api.tracker.yandex.net/v3/dashboards/123",
    "version": 1,
    "name": "Team plans",
    "layout": "one-column"
  }
]

Response parameters

Each array element contains dashboard parameters.

Parameter	Description	Data type
id	Dashboard ID.	Number
self	URL of the API resource with dashboard parameters.	String
version	Dashboard version.	Number
name	Dashboard name.	String
createdBy	Dashboard creator. User object fields.	Object
createdAt	Dashboard creation date and time.	String
layout	Widget display mode.	String
temp	Indicates a temporary dashboard.	Boolean
owner	Dashboard owner. User object fields.	Object

Response headers

Header	Description
Link	URLs for the first and next pages of results.
X-Total-Count	Total number of matching dashboards.
X-Total-Pages	Total number of pages for the selected `perPage`.

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.

Invalid pagination id parameter.

Was the article helpful?

Create a dashboard

Copy a dashboard