---
metadata:
  - name: generator
    content: Diplodoc Platform v5.64.0
  - property: og:type
    content: article
  - property: article:section
    content: API reference
  - property: og:title
    content: Searching dashboards
alternate:
  - https://yandex.com.tr/support/tracker/en/api/dashboards/search-dashboards.md
  - href: https://yandex.com.tr/support/tracker/en/api/dashboards/search-dashboards.md
    type: text/markdown
    title: Markdown version
  - href: https://yandex.com.tr/support/tracker/en/llms.txt?revision=r21825371
    rel: describedby
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.com.tr/support/tracker/en/llms.txt?revision=r21825371


# Searching dashboards

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

<div class="request_example yfm-code-floating-container method_post">
    <p>POST</p>
    <pre><code>https://api.tracker.yandex.net/v3/dashboards/_search</code></pre>
    <button class="yfm-clipboard-button"><svg width="16" height="16" viewBox="0 0 24 24" class="yfm-clipboard-icon" data-animation="15">
    <path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path>
    <path stroke="currentColor" fill="transparent" strokewidth="1.5" d="M9.5 13l3 3l5 -5" visibility="hidden">
        <animate id="visibileAnimation-15" attributeName="visibility" from="hidden" to="visible" dur="0.2s" fill="freeze" begin=""></animate>
        <animate id="hideAnimation-15" attributeName="visibility" from="visible" to="hidden" dur="1s" begin="visibileAnimation-15.end+1" fill="freeze"></animate>
    </path>
</svg>
</button>
</div>

<!-- source: en/api/_assets/style/methods.md -->

<!-- endsource: en/api/_assets/style/methods.md -->

## Request format {#request}

Before making a request, [get permission to access the API](https://yandex.com.tr/support/tracker/en/api/access.md). Pass search parameters in the JSON request body.

```json translate=no
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"}
}
```

<!-- source: en/api/_includes/headings.md -->
{% cut "Headers" %}

* `Host`: address of the node that provides the API.

* <!-- source: en/api/_includes/authorization.md -->
  `Authorization`: Authorization token about these formats:

    - `OAuth OAUTH_TOKEN`: For authorization using the OAuth 2.0 protocol. [Learn more](https://yandex.com.tr/support/tracker/en/api/access.md#about_OAuth)

    - `Bearer IAM_TOKEN`: For authorization using an IAM token, if a Yandex Identity Hub organization is linked to Tracker. [Learn more](https://yandex.com.tr/support/tracker/en/api/access.md#iam-token)
  <!-- endsource: en/api/_includes/authorization.md -->


* <!-- source: en/api/_includes/org-id.md -->
  # ID types {#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 {#find-id}


  To get the organization ID, go to **Administration** → [**Organizations**](https://tracker.yandex.com/admin/orgs) and copy the value from the **ID** field.
  <!-- endsource: en/api/_includes/org-id.md -->


{% endcut %}
<!-- endsource: en/api/_includes/headings.md -->

{% cut "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 ||
|#

{% endcut %}

{% cut "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 ||
|#

{% endcut %}

## Pagination mechanism {#pagination}

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.

1. To get the first page, make the request without the `id` parameter.
1. 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.
1. 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 {#pagination-example}

1. Get the first page:

    ```json translate=no
    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"
    }
    ```

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

    ```json translate=no
    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 {#response}

{% list tabs %}

- Request executed successfully

    <!-- source: en/api/_includes/answer-200.md -->
    If the request is successful, the API returns a response with code `200 OK`.
    <!-- endsource: en/api/_includes/answer-200.md -->

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

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


    {% cut "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](https://yandex.com.tr/support/tracker/en/api/dashboards/create-dashboard.md#user). | 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](https://yandex.com.tr/support/tracker/en/api/dashboards/create-dashboard.md#user). | Object ||
    |#

    {% endcut %}

    {% cut "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`. ||
    |#

    {% endcut %}

- Request failed

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

    <!-- source: en/api/_includes/answer-error-400.md -->
    400
    :   One or more request parameters have an invalid value.
    <!-- endsource: en/api/_includes/answer-error-400.md -->

    Invalid pagination `id` parameter.

{% endlist %}