Add order_by field to timeseries widget request schema

.generator/schemas/v1/openapi.yaml

@@ -25954,6 +25954,8 @@ components:
           $ref: '#/components/schemas/WidgetLineType'
         line_width:
           $ref: '#/components/schemas/WidgetLineWidth'
+        order_by:
+          $ref: '#/components/schemas/WidgetStyleOrderBy'
         palette:
           description: Color palette to apply to the widget.
           type: string
@@ -26016,6 +26018,19 @@ components:
           description: Color palette to apply to the widget.
           type: string
       type: object
+    WidgetStyleOrderBy:
+      description: 'How to order series in timeseries visualizations.
+
+        - `tags`: Order series alphabetically by tag name (default behavior)
+
+        - `values`: Order series by their current metric values (typically descending)'
+      enum:
+      - tags
+      - values
+      type: string
+      x-enum-varnames:
+      - TAGS
+      - VALUES
     WidgetSummaryType:
       description: Which summary type should be used.
       enum:

docs/datadog_api_client.v1.model.rst

@@ -6857,6 +6857,13 @@ datadog\_api\_client.v1.model.widget\_style module
    :members:
    :show-inheritance:
 
+datadog\_api\_client.v1.model.widget\_style\_order\_by module
+-------------------------------------------------------------
+
+.. automodule:: datadog_api_client.v1.model.widget_style_order_by
+   :members:
+   :show-inheritance:
+
 datadog\_api\_client.v1.model.widget\_summary\_type module
 ----------------------------------------------------------
 

examples/v1/dashboards/CreateDashboard_1259346254.py

@@ -0,0 +1,44 @@
+"""
+Create a new dashboard with timeseries widget using order_by values
+"""
+
+from datadog_api_client import ApiClient, Configuration
+from datadog_api_client.v1.api.dashboards_api import DashboardsApi
+from datadog_api_client.v1.model.dashboard import Dashboard
+from datadog_api_client.v1.model.dashboard_layout_type import DashboardLayoutType
+from datadog_api_client.v1.model.timeseries_widget_definition import TimeseriesWidgetDefinition
+from datadog_api_client.v1.model.timeseries_widget_definition_type import TimeseriesWidgetDefinitionType
+from datadog_api_client.v1.model.timeseries_widget_request import TimeseriesWidgetRequest
+from datadog_api_client.v1.model.widget import Widget
+from datadog_api_client.v1.model.widget_display_type import WidgetDisplayType
+from datadog_api_client.v1.model.widget_request_style import WidgetRequestStyle
+from datadog_api_client.v1.model.widget_style_order_by import WidgetStyleOrderBy
+
+body = Dashboard(
+    layout_type=DashboardLayoutType.ORDERED,
+    title="Example-Dashboard with order_by values",
+    widgets=[
+        Widget(
+            definition=TimeseriesWidgetDefinition(
+                type=TimeseriesWidgetDefinitionType.TIMESERIES,
+                requests=[
+                    TimeseriesWidgetRequest(
+                        q="avg:system.cpu.user{*} by {host}",
+                        style=WidgetRequestStyle(
+                            palette="warm",
+                            order_by=WidgetStyleOrderBy.VALUES,
+                        ),
+                        display_type=WidgetDisplayType.LINE,
+                    ),
+                ],
+            ),
+        ),
+    ],
+)
+
+configuration = Configuration()
+with ApiClient(configuration) as api_client:
+    api_instance = DashboardsApi(api_client)
+    response = api_instance.create_dashboard(body=body)
+
+    print(response)

examples/v1/dashboards/CreateDashboard_3631423980.py

@@ -0,0 +1,46 @@
+"""
+Create a new dashboard with timeseries widget without order_by for backward compatibility
+"""
+
+from datadog_api_client import ApiClient, Configuration
+from datadog_api_client.v1.api.dashboards_api import DashboardsApi
+from datadog_api_client.v1.model.dashboard import Dashboard
+from datadog_api_client.v1.model.dashboard_layout_type import DashboardLayoutType
+from datadog_api_client.v1.model.timeseries_widget_definition import TimeseriesWidgetDefinition
+from datadog_api_client.v1.model.timeseries_widget_definition_type import TimeseriesWidgetDefinitionType
+from datadog_api_client.v1.model.timeseries_widget_request import TimeseriesWidgetRequest
+from datadog_api_client.v1.model.widget import Widget
+from datadog_api_client.v1.model.widget_display_type import WidgetDisplayType
+from datadog_api_client.v1.model.widget_line_type import WidgetLineType
+from datadog_api_client.v1.model.widget_line_width import WidgetLineWidth
+from datadog_api_client.v1.model.widget_request_style import WidgetRequestStyle
+
+body = Dashboard(
+    layout_type=DashboardLayoutType.ORDERED,
+    title="Example-Dashboard without order_by",
+    widgets=[
+        Widget(
+            definition=TimeseriesWidgetDefinition(
+                type=TimeseriesWidgetDefinitionType.TIMESERIES,
+                requests=[
+                    TimeseriesWidgetRequest(
+                        q="avg:system.cpu.user{*} by {host}",
+                        style=WidgetRequestStyle(
+                            palette="dog_classic",
+                            line_type=WidgetLineType.SOLID,
+                            line_width=WidgetLineWidth.NORMAL,
+                        ),
+                        display_type=WidgetDisplayType.LINE,
+                    ),
+                ],
+            ),
+        ),
+    ],
+)
+
+configuration = Configuration()
+with ApiClient(configuration) as api_client:
+    api_instance = DashboardsApi(api_client)
+    response = api_instance.create_dashboard(body=body)
+
+    print(response)

examples/v1/dashboards/CreateDashboard_416487533.py

@@ -0,0 +1,44 @@
+"""
+Create a new dashboard with timeseries widget using order_by tags
+"""
+
+from datadog_api_client import ApiClient, Configuration
+from datadog_api_client.v1.api.dashboards_api import DashboardsApi
+from datadog_api_client.v1.model.dashboard import Dashboard
+from datadog_api_client.v1.model.dashboard_layout_type import DashboardLayoutType
+from datadog_api_client.v1.model.timeseries_widget_definition import TimeseriesWidgetDefinition
+from datadog_api_client.v1.model.timeseries_widget_definition_type import TimeseriesWidgetDefinitionType
+from datadog_api_client.v1.model.timeseries_widget_request import TimeseriesWidgetRequest
+from datadog_api_client.v1.model.widget import Widget
+from datadog_api_client.v1.model.widget_display_type import WidgetDisplayType
+from datadog_api_client.v1.model.widget_request_style import WidgetRequestStyle
+from datadog_api_client.v1.model.widget_style_order_by import WidgetStyleOrderBy
+
+body = Dashboard(
+    layout_type=DashboardLayoutType.ORDERED,
+    title="Example-Dashboard with order_by tags",
+    widgets=[
+        Widget(
+            definition=TimeseriesWidgetDefinition(
+                type=TimeseriesWidgetDefinitionType.TIMESERIES,
+                requests=[
+                    TimeseriesWidgetRequest(
+                        q="avg:system.cpu.user{*} by {host}",
+                        style=WidgetRequestStyle(
+                            palette="dog_classic",
+                            order_by=WidgetStyleOrderBy.TAGS,
+                        ),
+                        display_type=WidgetDisplayType.LINE,
+                    ),
+                ],
+            ),
+        ),
+    ],
+)
+
+configuration = Configuration()
+with ApiClient(configuration) as api_client:
+    api_instance = DashboardsApi(api_client)
+    response = api_instance.create_dashboard(body=body)
+
+    print(response)

src/datadog_api_client/v1/model/widget_request_style.py

@@ -16,30 +16,35 @@
 if TYPE_CHECKING:
     from datadog_api_client.v1.model.widget_line_type import WidgetLineType
     from datadog_api_client.v1.model.widget_line_width import WidgetLineWidth
+    from datadog_api_client.v1.model.widget_style_order_by import WidgetStyleOrderBy
 
 
 class WidgetRequestStyle(ModelNormal):
     @cached_property
     def openapi_types(_):
         from datadog_api_client.v1.model.widget_line_type import WidgetLineType
         from datadog_api_client.v1.model.widget_line_width import WidgetLineWidth
+        from datadog_api_client.v1.model.widget_style_order_by import WidgetStyleOrderBy
 
         return {
             "line_type": (WidgetLineType,),
             "line_width": (WidgetLineWidth,),
+            "order_by": (WidgetStyleOrderBy,),
             "palette": (str,),
         }
 
     attribute_map = {
         "line_type": "line_type",
         "line_width": "line_width",
+        "order_by": "order_by",
         "palette": "palette",
     }
 
     def __init__(
         self_,
         line_type: Union[WidgetLineType, UnsetType] = unset,
         line_width: Union[WidgetLineWidth, UnsetType] = unset,
+        order_by: Union[WidgetStyleOrderBy, UnsetType] = unset,
         palette: Union[str, UnsetType] = unset,
         **kwargs,
     ):
@@ -52,13 +57,21 @@ def __init__(
         :param line_width: Width of line displayed.
         :type line_width: WidgetLineWidth, optional
 
+        :param order_by: How to order series in timeseries visualizations.
+
+            * ``tags`` : Order series alphabetically by tag name (default behavior)
+            * ``values`` : Order series by their current metric values (typically descending)
+        :type order_by: WidgetStyleOrderBy, optional
+
         :param palette: Color palette to apply to the widget.
         :type palette: str, optional
         """
         if line_type is not unset:
             kwargs["line_type"] = line_type
         if line_width is not unset:
             kwargs["line_width"] = line_width
+        if order_by is not unset:
+            kwargs["order_by"] = order_by
         if palette is not unset:
             kwargs["palette"] = palette
         super().__init__(kwargs)

src/datadog_api_client/v1/model/widget_style_order_by.py

@@ -0,0 +1,40 @@
+# Unless explicitly stated otherwise all files in this repository are licensed under the Apache-2.0 License.
+# This product includes software developed at Datadog (https://www.datadoghq.com/).
+# Copyright 2019-Present Datadog, Inc.
+from __future__ import annotations
+
+
+from datadog_api_client.model_utils import (
+    ModelSimple,
+    cached_property,
+)
+
+from typing import ClassVar
+
+
+class WidgetStyleOrderBy(ModelSimple):
+    """
+    How to order series in timeseries visualizations.
+        - `tags`: Order series alphabetically by tag name (default behavior)
+        - `values`: Order series by their current metric values (typically descending)
+
+    :param value: Must be one of ["tags", "values"].
+    :type value: str
+    """
+
+    allowed_values = {
+        "tags",
+        "values",
+    }
+    TAGS: ClassVar["WidgetStyleOrderBy"]
+    VALUES: ClassVar["WidgetStyleOrderBy"]
+
+    @cached_property
+    def openapi_types(_):
+        return {
+            "value": (str,),
+        }
+
+
+WidgetStyleOrderBy.TAGS = WidgetStyleOrderBy("tags")
+WidgetStyleOrderBy.VALUES = WidgetStyleOrderBy("values")

src/datadog_api_client/v1/models/__init__.py

@@ -1138,6 +1138,7 @@
 from datadog_api_client.v1.model.widget_sort_by import WidgetSortBy
 from datadog_api_client.v1.model.widget_sort_order_by import WidgetSortOrderBy
 from datadog_api_client.v1.model.widget_style import WidgetStyle
+from datadog_api_client.v1.model.widget_style_order_by import WidgetStyleOrderBy
 from datadog_api_client.v1.model.widget_summary_type import WidgetSummaryType
 from datadog_api_client.v1.model.widget_text_align import WidgetTextAlign
 from datadog_api_client.v1.model.widget_tick_edge import WidgetTickEdge
@@ -2128,6 +2129,7 @@
     "WidgetSortBy",
     "WidgetSortOrderBy",
     "WidgetStyle",
+    "WidgetStyleOrderBy",
     "WidgetSummaryType",
     "WidgetTextAlign",
     "WidgetTickEdge",

tests/v1/cassettes/test_scenarios/test_create_a_new_dashboard_with_timeseries_widget_using_order_by_tags.frozen

@@ -0,0 +1 @@
+2026-01-20T23:39:22.864Z

tests/v1/cassettes/test_scenarios/test_create_a_new_dashboard_with_timeseries_widget_using_order_by_tags.yaml

@@ -0,0 +1,40 @@
+interactions:
+- request:
+    body: '{"layout_type":"ordered","title":"Test-Create_a_new_dashboard_with_timeseries_widget_using_order_by_tags-1768952362
+      with order_by tags","widgets":[{"definition":{"requests":[{"display_type":"line","q":"avg:system.cpu.user{*}
+      by {host}","style":{"order_by":"tags","palette":"dog_classic"}}],"type":"timeseries"}}]}'
+    headers:
+      accept:
+      - application/json
+      content-type:
+      - application/json
+    method: POST
+    uri: https://api.datadoghq.com/api/v1/dashboard
+  response:
+    body:
+      string: '{"id":"2r3-a4g-ubz","title":"Test-Create_a_new_dashboard_with_timeseries_widget_using_order_by_tags-1768952362
+        with order_by tags","description":null,"author_handle":"frog@datadoghq.com","author_name":"frog","layout_type":"ordered","url":"/dashboard/2r3-a4g-ubz/test-createanewdashboardwithtimeserieswidgetusingorderbytags-1768952362-with-ord","template_variables":null,"widgets":[{"definition":{"requests":[{"display_type":"line","q":"avg:system.cpu.user{*}
+        by {host}","style":{"order_by":"tags","palette":"dog_classic"}}],"type":"timeseries"},"id":8704189893014651}],"notify_list":null,"created_at":"2026-01-20T23:39:22.992533+00:00","modified_at":"2026-01-20T23:39:22.992533+00:00","restricted_roles":[]}'
+    headers:
+      content-type:
+      - application/json
+    status:
+      code: 200
+      message: OK
+- request:
+    body: null
+    headers:
+      accept:
+      - application/json
+    method: DELETE
+    uri: https://api.datadoghq.com/api/v1/dashboard/2r3-a4g-ubz
+  response:
+    body:
+      string: '{"deleted_dashboard_id":"2r3-a4g-ubz"}'
+    headers:
+      content-type:
+      - application/json
+    status:
+      code: 200
+      message: OK
+version: 1

tests/v1/cassettes/test_scenarios/test_create_a_new_dashboard_with_timeseries_widget_using_order_by_values.frozen

@@ -0,0 +1 @@
+2026-01-20T23:39:50.889Z

tests/v1/cassettes/test_scenarios/test_create_a_new_dashboard_with_timeseries_widget_using_order_by_values.yaml

@@ -0,0 +1,40 @@
+interactions:
+- request:
+    body: '{"layout_type":"ordered","title":"Test-Create_a_new_dashboard_with_timeseries_widget_using_order_by_values-1768952390
+      with order_by values","widgets":[{"definition":{"requests":[{"display_type":"line","q":"avg:system.cpu.user{*}
+      by {host}","style":{"order_by":"values","palette":"warm"}}],"type":"timeseries"}}]}'
+    headers:
+      accept:
+      - application/json
+      content-type:
+      - application/json
+    method: POST
+    uri: https://api.datadoghq.com/api/v1/dashboard
+  response:
+    body:
+      string: '{"id":"5ee-dqv-ruw","title":"Test-Create_a_new_dashboard_with_timeseries_widget_using_order_by_values-1768952390
+        with order_by values","description":null,"author_handle":"frog@datadoghq.com","author_name":"frog","layout_type":"ordered","url":"/dashboard/5ee-dqv-ruw/test-createanewdashboardwithtimeserieswidgetusingorderbyvalues-1768952390-with-o","template_variables":null,"widgets":[{"definition":{"requests":[{"display_type":"line","q":"avg:system.cpu.user{*}
+        by {host}","style":{"order_by":"values","palette":"warm"}}],"type":"timeseries"},"id":8314193502199768}],"notify_list":null,"created_at":"2026-01-20T23:39:51.018015+00:00","modified_at":"2026-01-20T23:39:51.018015+00:00","restricted_roles":[]}'
+    headers:
+      content-type:
+      - application/json
+    status:
+      code: 200
+      message: OK
+- request:
+    body: null
+    headers:
+      accept:
+      - application/json
+    method: DELETE
+    uri: https://api.datadoghq.com/api/v1/dashboard/5ee-dqv-ruw
+  response:
+    body:
+      string: '{"deleted_dashboard_id":"5ee-dqv-ruw"}'
+    headers:
+      content-type:
+      - application/json
+    status:
+      code: 200
+      message: OK
+version: 1

tests/v1/cassettes/test_scenarios/test_create_a_new_dashboard_with_timeseries_widget_without_order_by_for_backward_compatibility.frozen

@@ -0,0 +1 @@
+2026-01-20T23:40:15.566Z