## Query format {#query}
Before making a request, [get permission to access the API](https://yandex.ru/support/tracker/en/api/access.md).
To update a widget, use an HTTP `PATCH` request. In the request body, specify the parameters in JSON format.
```json translate=no
PATCH /v3/widgets/{widget_id}?version=WIDGET_VERSION
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": 20,
"fields": ["summary"],
"filterParams": {
"filter": {
"author": "me()"
}
}
}
```
{% cut "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](https://yandex.ru/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.ru/support/tracker/en/api/access.md#iam-token)
*
# 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.
{% endcut %}
{% cut "Resource" %}
#|
|| **Parameter** | **Description** | **Data type** ||
|| widget_id | Widget ID. | Number ||
|#
{% endcut %}
{% cut "Request parameters" %}
**Required parameters**
#|
|| **Parameter** | **Description** | **Data type** ||
|| version | Current widget version. Pass the version received in the response to the [Getting a widget](https://yandex.ru/support/tracker/en/api/dashboards/get-widget.md) or [Creating a widget](https://yandex.ru/support/tracker/en/api/dashboards/create-dashboard-widget.md) request. Each change to the widget increases the version number. | Number ||
|#
{% endcut %}
{% cut "Request body parameters" %}
Pass `type` and only the fields to update. Omitted fields retain their current values. The tables below describe fields for each type; required fields are indicated for widget creation.
#|
|| **Parameter** | **Description** | **Data type** ||
|| type | Widget type. Must match the type of the widget being updated; otherwise, the API returns `404`. 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.
`note`: a note widget.
`invite-links`: an invitation links widget.
`orgAdmin`: the "Information for employees" widget.
`burndown-chart`: a burndown chart.
`cycle-time`: a cycle time chart.
`flow`: a flow chart.
`velocity`: a velocity chart.
`goalFilter`: the "Goals" widget.
`projectPortfolioFilter`: the "Projects and portfolios" widget.
| String ||
|| description | Widget name. Required for creation and import. | String ||
|| color | Widget color. Optional. | Number ||
|| refresh | Widget refresh interval. Optional. | Number ||
|#
**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](#fields). ||
|| perPage | Number of items per widget page. ||
|| queues | Queues for the security widget. ||
|| filterParams | Issue filtering parameters. See the [object description](#filterParams). ||
|| 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`. ||
|#
**Additional types for creation and update**
These types are available in widget creation and update requests. Import does not support them.
#|
|| **Widget type** | **Required parameters** | **Optional parameters** ||
|| `note` | `text`, `markupType`: `md`, `plain` | — ||
|| `burndown-chart` | `sprintId`, `withHolidays` | — ||
|| `goalFilter` | — | `filter`, `filterFieldsOrder`, `fields`, `perPage` ||
|| `projectPortfolioFilter` | — | `filter`, `filterFieldsOrder`, `fields`, `perPage` ||
|| `cycle-time` | — | `filter`, `query`, `filterId`, `fromStatuses`, `toStatuses`, `excludedStatuses`, `includedStatuses`, `forStatus`, `bucket`, `calendar`, `lines`, `mode`: `common-lines`, `common-lines-and-points`, `status-lines`, `autoUpdatable`, `start`, `end`, `targetY` ||
|| `flow` | — | `filter`, `query`, `filterId`, `bucket`, `showIssues`: `SHOW_ALL`, `HIDE`, `fullView`, `mode`: `precise`, `smooth`, `statusColors`, `autoUpdatable`, `start`, `end` ||
|| `velocity` | `calculationSettings` | `filter`, `query`, `filterId`, `bucket`, `autoUpdatable`, `start`, `end` ||
|#
The `invite-links` and `orgAdmin` widgets use only the common parameters `description`, `color`, and `refresh`.
For `goalFilter`, `fields` specifies goal fields; for `projectPortfolioFilter`, it specifies project and portfolio fields. `perPage` accepts values from 1 to 50.
For `flow` and `velocity`, pass only one issue source: `filter`, `query`, or `filterId`.
#|
|| **Parameter** | **Description** ||
|| text, markupType | Note text and markup format: `md` or `plain`. ||
|| sprintId, withHolidays | Sprint ID and whether to account for non-working days. ||
|| filterFieldsOrder | Filter field order. ||
|| filter, query, filterId | Issue source: a filter, a query string, or a saved filter ID. ||
|| fromStatuses, toStatuses, excludedStatuses, includedStatuses, forStatus | Status parameters for the cycle time chart. ||
|| calendar | Calendar for chart calculations. ||
|| autoUpdatable | Automatic chart updates. ||
|| targetY | Target value for the cycle time chart. ||
|| fullView | Full flow chart view. ||
|| bucket | Grouping interval: `{"type": "days", "count": 1}`. Use `weeks` or `months` instead of `days` if needed. To group by sprint: `{"type": "sprints", "board": 123}`. Default: `{"type": "days", "count": 1}`. ||
|| start, end | Chart period boundaries: a date or an expression such as `now() - 3d`. `start` must not be later than `end`. Here, `start` is the chart period start; in import requests, `start` is the widget creation date. ||
|| lines | A `cycle-time` line settings object: Boolean `movingAverage` and `standardDeviation`, an array of numbers `percentile`, and a number `cakePercentile`. ||
|| statusColors | An array of status colors for `flow`, such as `[{"status": "open", "color": "#00AA00"}]`. ||
|| calculationSettings | Velocity calculation settings object. Supported `type` values are listed below. ||
|#
**Fields of the** `calculationSettings` **object**
#|
|| **type value** | **Parameters** ||
|| `byCompletedTasks` | `toStatuses` ||
|| `byWorklog` | `toStatuses` ||
|| `byStatuses` | `statuses`, `calendar` ||
|| `byNumericField` | `valueField`, `toStatuses`, `strategy` ||
|#
For `byStatuses`, `calendar` is required. For `byNumericField`, `valueField` is required: an integer, long, float, or worklog duration field. `strategy` is an object with `type` set to `byValueChangingSmooth` or `byValueChangingPrecise`, and a Boolean `byValueIncreasing`.
`planCalculationSettings` set to `{"type": "byOriginalValue"}` inside `calculationSettings` is supported only for `byCompletedTasks` and `byNumericField` with a `sprints` bucket. For `byNumericField`, it is incompatible with `"byValueIncreasing": true`.
**Elements of the** `fields` **array** {#fields}
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`](https://yandex.ru/support/tracker/en/api/issues/get-issue-fields.md).
**Object fields** `filterParams` {#filterParams}
#|
|| **Parameter** | **Description** | **Data type** ||
|| filter | Filter issues by parameters in the `{"FIELD": "VALUE"}` format. | Object ||
|| query | Issue filter in the [query language](https://yandex.com/support/tracker/user/query-filter.html). | String ||
|#
{% note info "" %}
If both `filter` and `query` are specified in the request body, `query` (the query language) takes precedence as the issue source.
{% endnote %}
{% endcut %}
## Response format {#answer}
{% list tabs %}
- Request executed successfully
If the request is successful, the API returns a response with code `200 OK`.
The response body contains a JSON object with the updated 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](https://yandex.ru/support/tracker/en/api/dashboards/get-widget.md) request.
```json translate=no
{
"id": 123456,
"version": 2,
"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/8000000000000007",
"id": "11********",
"display": "User Name",
"cloudUid": "ajeppa7dgp53********",
"passportUid": 1100000000000000
},
"description": "new desc-2",
"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": 20,
"filterParams": {
"filter": {
"author": "me()"
}
}
}
```
{% cut "Response parameters" %}
#|
|| **Parameter** | **Description** | **Data type** ||
|| id | Widget ID. | Number ||
|| version | Widget version. Each change to the widget increases the version number. | Number ||
|| type | Widget type. | String ||
|| self | URL of the API resource containing widget parameters. | String ||
|| [dashboard](#dashboard) | Object with information about the dashboard containing the widget. | Object ||
|| [createdBy](#user) | Object with information about the widget creator. | Object ||
|| description | Widget name. | String ||
|| text | Note text. Returned for `note` widgets. | 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](#fields-answer) | 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](#filterParams-answer) | Issue filtering parameters for the widget. | Object ||
|#
**Fields of objects in the** `fromStatuses` **and** `toStatuses` **arrays** {#statuses}
| Parameter | Description | Data type |
----- | ----- | -----
| self | Address of the API resource with information about the status. | String |
| id | Status ID. | String |
| key | Status key. | String |
| display | Status name displayed. | String |
**Object fields** `dashboard` {#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` {#user}
| 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** {#fields-answer}
#|
|| **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](#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](#queryProvider) | Field query provider. | Object ||
|| order | Field display order. | Number ||
|| [category](#category) | Field category. | Object ||
|| type | Field type. | String ||
|#
**Object fields** `schema` {#schema}
#|
|| **Parameter** | **Description** | **Data type** ||
|| type | Field data type. | String ||
|| required | Indicates that the field is required. | Boolean ||
|#
**Object fields** `queryProvider` {#queryProvider}
#|
|| **Parameter** | **Description** | **Data type** ||
|| type | Query provider type. | String ||
|#
**Object fields** `category` {#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` {#filterParams-answer}
#|
|| **Parameter** | **Description** | **Data type** ||
|| filter | Issue filter by parameters. | Object ||
|| query | Issue query, if specified. | String ||
|#
{% endcut %}
- Request failed
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.
409
: There was a conflict when editing the object. The error may be due to an invalid update version.
412
: A conflict occurred while editing the object. The error may be due to an invalid update version.
422
: JSON validation error, the request is rejected.
500
: Internal service error. Try again later.
503
: The API service is temporarily unavailable.
{% endlist %}