Importing a widget

Use this request to import a widget to an existing dashboard. Importing is useful for moving widgets between dashboards.

To place the widget on the dashboard, add it using the widgets.add parameter of the dashboard update request. Until then, the widget is not visible on the dashboard and is not returned in the widgets field of the Getting a dashboard request.

POST

https://api.tracker.yandex.net/v3/dashboards/{dashboard_id}/widgets/_import

Only an administrator can make this request.

Query format

Before making a request, get permission to access the API.

To import a widget, use an HTTP POST request. In the request body, specify widget parameters in JSON format.

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

{
    "type": "filter",
    "description": "WIDGET_NAME",
    "perPage": 10,
    "fields": ["summary"],
    "filterParams": {
        "filter": {
            "author": "me()"
        }
    },
    "createdBy": "USER_LOGIN",
    "start": "2025-02-18T16:35:41.740+0000"
}

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.

Resource

Parameter	Description	Data type
dashboard_id	Dashboard ID.	Number

Request body parameters

Specify type and the parameters for the selected widget type.

Parameter	Description	Data type
type	Widget type. Possible values: `info`: the "Useful links" widget. `security`: a security widget. `filter`: the "Issues" widget. `created-vs-resolved`: the "Created/Resolved" chart. `issues`: the "Issue statistics" widget. `table-sum`: the "Summary table with totals" widget. `table`: the "Summary table" widget. `time-since`: the "Event chart" widget.	String
description	Widget name. Required for creation and import.	String
color	Widget color. Optional.	Number
refresh	Widget refresh interval. Optional.	Number
createdBy	Widget creator login. Required.	String
start	Widget creation date and time in the `YYYY-MM-DDThh:mm:ss.sss±hhmm` format. Required.	String

Widget type parameters

Use the fields for the selected type. The fields in the second column are required for creation and import.

Widget type	Required parameters	Optional parameters
`info`	`subtype`: `links`, `presets`, `test_drive`	—
`security`	`fields`, `perPage`	`queues`
`filter`	`fields`, `perPage`, `filterParams`	—
`created-vs-resolved`	`filterParams`	`groupBy`, `daysCount`, `cumulative`, `unresolvedIssuesTrend`, `versions`: `all`, `main`, `none`
`issues`	`filterParams`, `field`, `perPage`	`orderBySum`, `orderAsc`
`table`	`filterParams`, `fieldX`, `fieldY`, `perPage`	`showSum`, `orderBySum`, `orderAsc`
`table-sum`	`filterParams`, `rowField`, `columnField`, `sumField`, `initialRowsLimit`	`showTotals`, `rowOrderAsc`, `columnOrderAsc`
`time-since`	`filterParams`, `field`	`groupBy`, `daysCount`, `cumulative`

Parameter	Description
subtype	Useful links subtype: `links`, `presets`, or `test_drive`.
fields	Fields to display. For issue widgets, see the array description.
perPage	Number of items per widget page.
queues	Queues for the security widget.
filterParams	Issue filtering parameters. See the object description.
field	Grouping field.
fieldX, fieldY	Table axis fields. `fieldY` must differ from `fieldX`.
rowField, columnField	Row and column fields. `columnField` must differ from `rowField`.
sumField	Field to sum.
initialRowsLimit	Initial row count: from 1 to 200.
showSum, showTotals	Display the sum and totals.
orderBySum, orderAsc	Sort by sum and in ascending order.
rowOrderAsc, columnOrderAsc	Sort rows and columns in ascending order.
groupBy	Grouping: `hour`, `day`, `week`, `month`, `quarter`, or `year`.
daysCount	Grouping period. Default: 30. The maximum depends on `groupBy`: `hour`: 10, `day`: 300, `week`: 1750, other values: 3500.
cumulative	Cumulative chart mode.
unresolvedIssuesTrend	Display the trend for unresolved issues.
versions	Versions for the Created/Resolved chart: `all`, `main`, or `none`.

Elements of the fields array

The fields parameter specifies the issue fields displayed in the widget. Each array element is an issue field key. For example, ["summary"] displays only the issue summary column in the widget.

Examples of standard issue field keys:

Parameter	Description
key	Issue key.
summary	Issue summary.
status	Issue status.
assignee	Assignee.
priority	Priority.
created	Issue creation date.
updated	Issue update date.

The full list of issue fields is available in the Tracker interface under Administration → Fields (https://tracker.yandex.com/admin/fields). You can also get the list using the API: GET /v3/fields.

Object fields filterParams

Parameter	Description	Data type
filter	Filter issues by parameters in the `{"FIELD": "VALUE"}` format.	Object
query	Issue filter in the query language.	String

If both filter and query are specified in the request body, query (the query language) takes precedence as the issue source.

Response format

Request executed successfully

Request failed

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

The response body contains a JSON object with the imported widget parameters.

The fields depend on the widget type. The example below shows a filter widget. Layout fields are returned only by the Getting a widget request.

{
    "id": 123456,
    "version": 1,
    "type": "filter",
    "self": "https://api.tracker.yandex.net/v3/widgets/123456",
    "dashboard": {
        "self": "https://api.tracker.yandex.net/v3/dashboards/18",
        "id": "18",
        "display": "New dashboard"
    },
    "createdBy": {
        "self": "https://api.tracker.yandex.net/v3/users/11********",
        "id": "11********",
        "display": "User Name",
        "cloudUid": "ajeppa7dgp53********",
        "passportUid": 1100000000000000
    },
    "description": "new desc",
    "color": 0,
    "createdAt": "2026-08-27T10:34:30.363+0000",
    "fields": [
        {
            "self": "https://api.tracker.yandex.net/v3/fields/summary",
            "id": "summary",
            "name": "Issue",
            "key": "summary",
            "version": 0,
            "schema": {
                "type": "string",
                "required": true
            },
            "readonly": false,
            "options": false,
            "suggest": false,
            "queryProvider": {
                "type": "SummaryQueryProvider"
            },
            "order": 6,
            "category": {
                "self": "https://api.tracker.yandex.net/v3/fields/categories/000000000000000000000001",
                "id": "000000000000000000000001",
                "display": "System"
            },
            "type": "standard"
        }
    ],
    "perPage": 10,
    "filterParams": {
        "filter": {
            "author": "Author"
        }
    }
}

Response parameters

Parameter	Description	Data type
id	Widget ID.	Number
version	Widget version.	Number
type	Widget type.	String
self	URL of the API resource containing widget parameters.	String
dashboard	Object with information about the dashboard containing the widget.	Object
createdBy	Object with information about the widget creator.	Object
description	Widget name.	String
color	Service parameter.	Number
createdAt	Date and time when the widget was created, in the `YYYY-MM-DDThh:mm:ss.sss±hhmm` format.	String
fields	Array of objects with information about the issue fields displayed in the widget.	Array of objects
perPage	Number of issues per widget page.	Number
filterParams	Issue filtering parameters for the widget.	Object

Object fields dashboard

Parameter	Description	Data type
self	URL of the API resource containing dashboard parameters.	String
id	Dashboard ID.	String
display	Dashboard name.	String

Object fields createdBy

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 Identity Hub	String

Fields of elements in the fields array

Parameter	Description	Data type
self	URL of the API resource containing field parameters.	String
id	Field ID.	String
name	Field name.	String
key	Field key.	String
version	Field version.	Number
schema	Field schema.	Object
readonly	Indicates that the field is read-only.	Boolean
options	Indicates that the field has a fixed set of values.	Boolean
suggest	Indicates that suggestions are available for the field.	Boolean
queryProvider	Field query provider.	Object
order	Field display order.	Number
category	Field category.	Object
type	Field type.	String

Object fields schema

Parameter	Description	Data type
type	Field data type.	String
required	Indicates that the field is required.	Boolean

Object fields queryProvider

Parameter	Description	Data type
type	Query provider type.	String

Object fields category

Parameter	Description	Data type
self	URL of the API resource containing category parameters.	String
id	Category ID.	String
display	Category name.	String

Object fields filterParams

Parameter	Description	Data type
filter	Issue filter by parameters.	Object
query	Issue query, if specified.	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.

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.

422: JSON validation error, the request is rejected.

500: Internal service error. Try again later.

503: The API service is temporarily unavailable.

Was the article helpful?

Update a widget

Get a list of components

Importing a widget

Query format

ID types

Finding the ID

Response format

Was the article helpful?