---
metadata:
  - name: generator
    content: Diplodoc Platform v5.47.3
alternate:
  - https://yandex.com.tr/support/tracker/en/api-ref/dashboards/create-widget.md
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.com.tr/support/tracker/en/llms.txt

# Creating a "Cycle time" widget

Use this request to add a widget with a ["Cycle time" chart](https://yandex.com.tr/support/tracker/en/user/cycle-time.md) to an existing dashboard.

<div class="request_example method_post yfm-clipboard">
    <p>POST</p>
    <pre><code>https://api.tracker.yandex.net/v3/dashboards/&lt;dashboard_ID>/widgets/cycleTime</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/_assets/style/methods.md -->

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

## Query format {#query}

Before making a request, [get permission to access the API](https://yandex.com.tr/support/tracker/en/api-ref/access.md).

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

```json
POST /v3/dashboards/<dashboard_ID>/widgets/cycleTime
Host: api.tracker.yandex.net
Authorization: OAuth <OAuth_token>
X-Org-ID or X-Cloud-Org-ID: <organization_ID>

{
    "description": "<widget_name>",
    "query" | "filter" | "filterId" : "<issue_filter>",
    "fromStatuses": [
        {
            "key": "<initial_status>"
        }
    ],
    "toStatuses": [
        {
            "key": "<final_status>"
        }
    ],
    "excludedStatuses": [<excluded_statuses>],
    "includedStatuses": [<included_statuses>],
    "bucket": {
        "unit": "<grouping_period>",
        "count": <period_count>
    },
    "calendar": <calendar_ID>,
    "lines": {
        "movingAverage": <true> | <false>,
        "standardDeviation": <true> | <false>,
        "percentile": [75, 83, 90],
        "cakePercentile": 85
    },
    "start": "now()-2w",
    "end": "now()-2d",
    "mode": "<data_display_mode>",
    "autoUpdatable": <true> | <false>
}
```

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

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

* <!-- source: en/_includes/api/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-ref/access.md#about_OAuth)

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


* <!-- source: en/_includes/api/org-id.md -->
  `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 Cloud Organization.

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


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

{% cut "Request body parameters" %}

The request body contains the parameters of the widget with the "Cycle time" chart.

**Required parameters**

| Parameter | Description | Data type |
-------- | -------- | ----------
| description | Widget name. | String |

**Additional parameters**

| Parameter | Description | Data type |
-------- | -------- | ----------
| query | Issue filter in the [query language](../../user/query-filter.md). | String |
| filter | Issue filter in `{"<field>": "<value>"}` format. | String |
| filterId | ID of the [saved filter](../../user/create-filter.md). | String |
| fromStatuses | Status key of the issue at the time the work on the issue started. Time spent in the specified status is not counted. By default, calculation starts with the first status in the issue history. | Array |
| toStatuses | Status key of the issue at the time of issue completion. If multiple statuses are specified, the last status that the issue changed to is used. By default, calculation ends with the last status in the issue history. | Array |
| excludedStatuses | Statuses for which the time spent should be excluded from calculations. | Array |
| includedStatuses | Statuses for which the time spent should be included in calculations. | Array |
| [bucket](#bucket) | Step value. 7 days is the default. | Map item |
| calendar | [Calendar](../../manager/schedule.md) ID for tracking working hours only. If omitted, the standard calendar is used. | Number |
| [lines](#lines) | Display settings for the time axis. | Map item |
| start | Starting formula for the calculation. Sample formula to calculate for the past two weeks: `now() - 2w`. 2 years is the default. | String |
| end | End formula for the calculation. Sample formula to end calculations two days prior to the current date: `now() - 2d`. `now()` is the default. | String |
| mode | Data display mode: <ul><li>`common-lines`: Show selected charts (a percentile, the standard deviation, or a moving average).</li><li>`common-lines-and-points`: Show points that correspond to issues for selected charts.</li><li>`status-lines`: Show selected charts for each status.</li> | String |
| autoUpdatable | Flag of chart auto update. | Boolean |

`bucket` **object fields** {#bucket}

| Parameter | Description | Data type |
-------- | -------- | ----------
| unit | Date grouping period: <ul><li>`Days`</li><li>`Weeks`</li><li>`Months`</li><li>`Sprints`</li></ul> | String |
| count | Number of periods with selected grouping. If the `unit` field value is `sprints`, the number of periods is always 1. | Number |
| boardId | Issue board ID. Available if the `unit` field value is `sprints`. | String |

`lines` **object fields** {#lines}

| Parameter | Description | Data type |
-------- | -------- | ----------
| movingAverage | Moving average. This option adds the line of the average time value to the chart. It allows you to see how the issue goes through the cycle by the median. | Boolean |
| standardDeviation | Standard deviation. This option adds the line of mean square deviation to the chart. It can help you estimate how widely the values are scattered from the average. | Boolean |
| percentile | Percentage of values in the data sample against which the percentile is calculated. | Array |
| cakePercentile | Percentile value for creating a chart where each status is displayed separately. | Number |

{% endcut %}

## Response format {#answer}

{% list tabs %}

- Request executed successfully

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

    The response body contains a JSON object with the new widget's parameters.

    ```json
    {
        "id": 123456,
        "version": 1,
        "createdBy": {
            "self": "https://api.tracker.yandex.net/v3/users/12********",
            "id": "44********",
            "display": "John Smith",
            "passportUid": 12********
        },
        "description": "Cycle time chart",
        "color": 0,
        "dashboard": {
            "self": "https://api.tracker.yandex.net/v3/dashboards/118899",
            "id": "118899",
            "display": "Dashboard"
        },
        "fromStatuses": [
            {
                "self": "https://api.tracker.yandex.net/v3/statuses/1",
                "id": "1",
                "key": "open",
                "display": "Open"
            }
        ],
        "toStatuses": [
            {
                "self": "https://api.tracker.yandex.net/v3/statuses/3",
                "id": "3",
                "key": "closed",
                "display": "Closed"
            }
        ],
        "bucket": {
            "type": "days",
            "count": 2
        },
        "calendar": {
            "id": "1",
            "display": "Moscow. Weekdays, 11:00−20:00"
        },
        "query": "Queue: TEST Assignee: me()",
        "datasetInfo": {
            "status": "created",
            "buildStartedAt": "2024-04-15T20:58:07.957+0000",
            "builtBy": {
                "self": "https://api.tracker.yandex.net/v3/users/12********",
                "id": "44********",
                "display": "John Smith",
                "passportUid": 12********
            },
        },
        "lines": {
            "standardDeviation": true,
            "movingAverage": true,
            "percentile": [
                83.0,
                90.0,
                75.0
            ],
            "cakePercentile": 85.0
        },
        "start": "now()-2w",
        "end": "now()-2d",
        "mode": "common-lines-and-points",
        "self": "https://api.tracker.yandex.net/v3/widgets/123456"
    }
    ```

    {% cut "Response parameters" %}

    | Parameter | Description | Data type |
    -------- | -------- | ----------
    | id | Widget ID. | Number |
    | version | Widget version. The version number goes up whenever the widget is changed. | Number |
    | [createdBy](#user) | Object with information about the user who created the widget. | Map item |
    | description | Widget name. | String |
    | color | Service parameter | Number |
    | [dashboard](#dashboard) | Object with information about the dashboard where the widget is placed. | Map item |
    | [fromStatuses](#statuses) | Object that contains status information for the issue at the time the work started. | Map item |
    | [toStatuses](#statuses) | Object that contains status information for the issue at the time of issue completion. | Map item |
    | [bucket](#bucket-answer) | Object with step value information. | Map item |
    | [calendar](#calendar) | Object with information about the [working time schedule](../../manager/schedule.md). | Map item |
    | query \| filter \| filterId | Issue filter in the selected format. | String |
    | [datasetInfo](#datasetInfo) | Object with calculation information. | Map item |
    | [lines](#lines) | Object with time axis information. | Map item |
    | start | Starting formula for the calculation. | String |
    | end | End formula for the calculation. | String |
    | mode | Data display mode. | String |
    | self | Address of the API resource with widget parameters. | String |

    `createdBy` and `builtBy` **object fields** {#user}

    <!-- source: en/_includes/api/user.md -->
    | 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 Cloud Organization | String |
    <!-- endsource: en/_includes/api/user.md -->

    `dashboard` **object fields** {#dashboard}

    | Parameter | Description | Data type |
    -------- | -------- | ----------
    | self | Address of the API resource that contains the dashboard parameters. | String |
    | id | Dashboard ID. | String |
    | display | Dashboard name. | String |

    `bucket` **object fields** {#bucket-answer}

    | Parameter | Description | Data type |
    -------- | -------- | ----------
    | type | Date grouping period: <ul><li>`Days`</li><li>`Weeks`</li><li>`Months`</li><li>`Sprints`</li></ul> | String |
    | count | Number of periods with selected grouping. If the `unit` field value is `sprints`, the number of periods is always 1. | Number |
    | boardId | Issue board ID. Available if the `unit` field value is `sprints`. | String |

    `calendar` **object fields** {#calendar}

    | Parameter | Description | Data type |
    -------- | -------- | ----------
    | id | ID of the working time schedule. | String |
    | display | Name of the working time schedule. | String |

    `datasetInfo` **object fields** {#datasetInfo}

    | Parameter | Description | Data type |
    -------- | -------- | ----------
    | status | Calculation status. | String |
    | buildStartedAt | Calculation start date and time in ```YYYY-MM-DDThh:mm:ss.sss±hhmm``` format. | String |
    | [builtBy](#user) | Object with information about the user who created the widget. | Map item |

    `lines` **object fields** {#lines}

    | Parameter | Description | Data type |
    -------- | -------- | ----------
    | standardDeviation | Display flag for the standard deviation chart. | Boolean |
    | movingAverage | Display flag for the moving average chart. | Boolean |
    | percentile | List of percentage values in the data sample for which percentiles are calculated. | Array |
    | cakePercentile | Percentile value for creating a chart where each status is displayed separately. | Number |

    {% endcut %}

- Request failed

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

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

    <!-- source: en/_includes/api/answer-error-403.md -->
    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.
    <!-- endsource: en/_includes/api/answer-error-403.md -->

    <!-- source: en/_includes/api/answer-error-404.md -->
    404
    :   The requested object was not found. You may have specified an invalid object ID or key.
    <!-- endsource: en/_includes/api/answer-error-404.md -->

    <!-- source: en/_includes/api/answer-error-422.md -->
    422
    :   JSON validation error, the request is rejected.
    <!-- endsource: en/_includes/api/answer-error-422.md -->

    <!-- source: en/_includes/api/answer-error-500.md -->
    500
    :   Internal service error. Try again later.
    <!-- endsource: en/_includes/api/answer-error-500.md -->

    <!-- source: en/_includes/api/answer-error-503.md -->
    503
    :   The API service is temporarily unavailable.
    <!-- endsource: en/_includes/api/answer-error-503.md -->

{% endlist %}