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:

cassettes/features/v1/dashboards/Create-a-new-dashboard-with-timeseries-widget-using-order-by-tags.frozen

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

cassettes/features/v1/dashboards/Create-a-new-dashboard-with-timeseries-widget-using-order-by-values.frozen

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

cassettes/features/v1/dashboards/Create-a-new-dashboard-with-timeseries-widget-without-order-by-for-backward-compatibility.frozen

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

examples/v1/dashboards/CreateDashboard_1259346254.rb

@@ -0,0 +1,27 @@
+# Create a new dashboard with timeseries widget using order_by values
+
+require "datadog_api_client"
+api_instance = DatadogAPIClient::V1::DashboardsAPI.new
+
+body = DatadogAPIClient::V1::Dashboard.new({
+  layout_type: DatadogAPIClient::V1::DashboardLayoutType::ORDERED,
+  title: "Example-Dashboard with order_by values",
+  widgets: [
+    DatadogAPIClient::V1::Widget.new({
+      definition: DatadogAPIClient::V1::TimeseriesWidgetDefinition.new({
+        type: DatadogAPIClient::V1::TimeseriesWidgetDefinitionType::TIMESERIES,
+        requests: [
+          DatadogAPIClient::V1::TimeseriesWidgetRequest.new({
+            q: "avg:system.cpu.user{*} by {host}",
+            style: DatadogAPIClient::V1::WidgetRequestStyle.new({
+              palette: "warm",
+              order_by: DatadogAPIClient::V1::WidgetStyleOrderBy::VALUES,
+            }),
+            display_type: DatadogAPIClient::V1::WidgetDisplayType::LINE,
+          }),
+        ],
+      }),
+    }),
+  ],
+})
+p api_instance.create_dashboard(body)

examples/v1/dashboards/CreateDashboard_3631423980.rb

@@ -0,0 +1,28 @@
+# Create a new dashboard with timeseries widget without order_by for backward compatibility
+
+require "datadog_api_client"
+api_instance = DatadogAPIClient::V1::DashboardsAPI.new
+
+body = DatadogAPIClient::V1::Dashboard.new({
+  layout_type: DatadogAPIClient::V1::DashboardLayoutType::ORDERED,
+  title: "Example-Dashboard without order_by",
+  widgets: [
+    DatadogAPIClient::V1::Widget.new({
+      definition: DatadogAPIClient::V1::TimeseriesWidgetDefinition.new({
+        type: DatadogAPIClient::V1::TimeseriesWidgetDefinitionType::TIMESERIES,
+        requests: [
+          DatadogAPIClient::V1::TimeseriesWidgetRequest.new({
+            q: "avg:system.cpu.user{*} by {host}",
+            style: DatadogAPIClient::V1::WidgetRequestStyle.new({
+              palette: "dog_classic",
+              line_type: DatadogAPIClient::V1::WidgetLineType::SOLID,
+              line_width: DatadogAPIClient::V1::WidgetLineWidth::NORMAL,
+            }),
+            display_type: DatadogAPIClient::V1::WidgetDisplayType::LINE,
+          }),
+        ],
+      }),
+    }),
+  ],
+})
+p api_instance.create_dashboard(body)

examples/v1/dashboards/CreateDashboard_416487533.rb

@@ -0,0 +1,27 @@
+# Create a new dashboard with timeseries widget using order_by tags
+
+require "datadog_api_client"
+api_instance = DatadogAPIClient::V1::DashboardsAPI.new
+
+body = DatadogAPIClient::V1::Dashboard.new({
+  layout_type: DatadogAPIClient::V1::DashboardLayoutType::ORDERED,
+  title: "Example-Dashboard with order_by tags",
+  widgets: [
+    DatadogAPIClient::V1::Widget.new({
+      definition: DatadogAPIClient::V1::TimeseriesWidgetDefinition.new({
+        type: DatadogAPIClient::V1::TimeseriesWidgetDefinitionType::TIMESERIES,
+        requests: [
+          DatadogAPIClient::V1::TimeseriesWidgetRequest.new({
+            q: "avg:system.cpu.user{*} by {host}",
+            style: DatadogAPIClient::V1::WidgetRequestStyle.new({
+              palette: "dog_classic",
+              order_by: DatadogAPIClient::V1::WidgetStyleOrderBy::TAGS,
+            }),
+            display_type: DatadogAPIClient::V1::WidgetDisplayType::LINE,
+          }),
+        ],
+      }),
+    }),
+  ],
+})
+p api_instance.create_dashboard(body)

features/v1/dashboards.feature

@@ -946,6 +946,24 @@ Feature: Dashboards
     And the response "widgets[0].definition.requests[0].display_type" is equal to "bars"
     And the response "widgets[0].definition.requests[0].q" is equal to "sum:trace.test.errors{env:prod,service:datadog-api-spec} by {resource_name}.as_count()"
 
+  @team:DataDog/dashboards-backend
+  Scenario: Create a new dashboard with timeseries widget using order_by tags
+    Given new "CreateDashboard" request
+    And body with value {"layout_type": "ordered", "title": "{{ unique }} with order_by tags","widgets": [{"definition": {"type": "timeseries","requests": [{"q": "avg:system.cpu.user{*} by {host}","style": {"palette": "dog_classic","order_by": "tags"},"display_type": "line"}]}}]}
+    When the request is sent
+    Then the response status is 200 OK
+    And the response "widgets[0].definition.requests[0].style.order_by" is equal to "tags"
+    And the response "widgets[0].definition.requests[0].style.palette" is equal to "dog_classic"
+
+  @team:DataDog/dashboards-backend
+  Scenario: Create a new dashboard with timeseries widget using order_by values
+    Given new "CreateDashboard" request
+    And body with value {"layout_type": "ordered", "title": "{{ unique }} with order_by values","widgets": [{"definition": {"type": "timeseries","requests": [{"q": "avg:system.cpu.user{*} by {host}","style": {"palette": "warm","order_by": "values"},"display_type": "line"}]}}]}
+    When the request is sent
+    Then the response status is 200 OK
+    And the response "widgets[0].definition.requests[0].style.order_by" is equal to "values"
+    And the response "widgets[0].definition.requests[0].style.palette" is equal to "warm"
+
   @team:DataDog/dashboards-backend
   Scenario: Create a new dashboard with timeseries widget with custom_unit
     Given new "CreateDashboard" request
@@ -958,6 +976,16 @@ Feature: Dashboards
     And the response "widgets[0].definition.requests[0].formulas[0].number_format.unit.type" is equal to "canonical_unit"
     And the response "widgets[0].definition.requests[0].formulas[0].number_format.unit.unit_name" is equal to "fraction"
 
+  @team:DataDog/dashboards-backend
+  Scenario: Create a new dashboard with timeseries widget without order_by for backward compatibility
+    Given new "CreateDashboard" request
+    And body with value {"layout_type": "ordered", "title": "{{ unique }} without order_by","widgets": [{"definition": {"type": "timeseries","requests": [{"q": "avg:system.cpu.user{*} by {host}","style": {"palette": "dog_classic","line_type": "solid","line_width": "normal"},"display_type": "line"}]}}]}
+    When the request is sent
+    Then the response status is 200 OK
+    And the response "widgets[0].definition.requests[0].style.palette" is equal to "dog_classic"
+    And the response "widgets[0].definition.requests[0].style.line_type" is equal to "solid"
+    And the response "widgets[0].definition.requests[0].style.line_width" is equal to "normal"
+
   @team:DataDog/dashboards-backend
   Scenario: Create a new dashboard with toplist widget
     Given new "CreateDashboard" request

lib/datadog_api_client/inflector.rb

@@ -971,6 +971,7 @@ def overrides
           "v1.widget_sort_by" => "WidgetSortBy",
           "v1.widget_sort_order_by" => "WidgetSortOrderBy",
           "v1.widget_style" => "WidgetStyle",
+          "v1.widget_style_order_by" => "WidgetStyleOrderBy",
           "v1.widget_summary_type" => "WidgetSummaryType",
           "v1.widget_text_align" => "WidgetTextAlign",
           "v1.widget_tick_edge" => "WidgetTickEdge",

lib/datadog_api_client/v1/models/widget_request_style.rb

@@ -27,6 +27,11 @@ class WidgetRequestStyle
     # Width of line displayed.
     attr_accessor :line_width
 
+    # 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)
+    attr_accessor :order_by
+
     # Color palette to apply to the widget.
     attr_accessor :palette
 
@@ -38,6 +43,7 @@ def self.attribute_map
       {
         :'line_type' => :'line_type',
         :'line_width' => :'line_width',
+        :'order_by' => :'order_by',
         :'palette' => :'palette'
       }
     end
@@ -48,6 +54,7 @@ def self.openapi_types
       {
         :'line_type' => :'WidgetLineType',
         :'line_width' => :'WidgetLineWidth',
+        :'order_by' => :'WidgetStyleOrderBy',
         :'palette' => :'String'
       }
     end
@@ -78,6 +85,10 @@ def initialize(attributes = {})
         self.line_width = attributes[:'line_width']
       end
 
+      if attributes.key?(:'order_by')
+        self.order_by = attributes[:'order_by']
+      end
+
       if attributes.key?(:'palette')
         self.palette = attributes[:'palette']
       end
@@ -111,6 +122,7 @@ def ==(o)
       self.class == o.class &&
           line_type == o.line_type &&
           line_width == o.line_width &&
+          order_by == o.order_by &&
           palette == o.palette &&
           additional_properties == o.additional_properties
     end
@@ -119,7 +131,7 @@ def ==(o)
     # @return [Integer] Hash code
     # @!visibility private
     def hash
-      [line_type, line_width, palette, additional_properties].hash
+      [line_type, line_width, order_by, palette, additional_properties].hash
     end
   end
 end

lib/datadog_api_client/v1/models/widget_style_order_by.rb

@@ -0,0 +1,29 @@
+=begin
+#Datadog API V1 Collection
+
+#Collection of all Datadog Public endpoints.
+
+The version of the OpenAPI document: 1.0
+Contact: support@datadoghq.com
+Generated by: https://github.com/DataDog/datadog-api-client-ruby/tree/master/.generator
+
+ 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 2020-Present Datadog, Inc.
+
+=end
+
+require 'date'
+require 'time'
+
+module DatadogAPIClient::V1
+  # 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)
+  class WidgetStyleOrderBy
+    include BaseEnumModel
+
+    TAGS = "tags".freeze
+    VALUES = "values".freeze
+  end
+end