Add order_by field to timeseries widget request schema

.generator/schemas/v1/openapi.yaml

@@ -25934,6 +25934,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
@@ -25996,6 +25998,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:

examples/v1/dashboards/CreateDashboard_1259346254.java

@@ -0,0 +1,55 @@
+// Create a new dashboard with timeseries widget using order_by values
+
+import com.datadog.api.client.ApiClient;
+import com.datadog.api.client.ApiException;
+import com.datadog.api.client.v1.api.DashboardsApi;
+import com.datadog.api.client.v1.model.Dashboard;
+import com.datadog.api.client.v1.model.DashboardLayoutType;
+import com.datadog.api.client.v1.model.TimeseriesWidgetDefinition;
+import com.datadog.api.client.v1.model.TimeseriesWidgetDefinitionType;
+import com.datadog.api.client.v1.model.TimeseriesWidgetRequest;
+import com.datadog.api.client.v1.model.Widget;
+import com.datadog.api.client.v1.model.WidgetDefinition;
+import com.datadog.api.client.v1.model.WidgetDisplayType;
+import com.datadog.api.client.v1.model.WidgetRequestStyle;
+import com.datadog.api.client.v1.model.WidgetStyleOrderBy;
+import java.util.Collections;
+
+public class Example {
+  public static void main(String[] args) {
+    ApiClient defaultClient = ApiClient.getDefaultApiClient();
+    DashboardsApi apiInstance = new DashboardsApi(defaultClient);
+
+    Dashboard body =
+        new Dashboard()
+            .layoutType(DashboardLayoutType.ORDERED)
+            .title("Example-Dashboard with order_by values")
+            .widgets(
+                Collections.singletonList(
+                    new Widget()
+                        .definition(
+                            new WidgetDefinition(
+                                new TimeseriesWidgetDefinition()
+                                    .type(TimeseriesWidgetDefinitionType.TIMESERIES)
+                                    .requests(
+                                        Collections.singletonList(
+                                            new TimeseriesWidgetRequest()
+                                                .q("avg:system.cpu.user{*} by {host}")
+                                                .style(
+                                                    new WidgetRequestStyle()
+                                                        .palette("warm")
+                                                        .orderBy(WidgetStyleOrderBy.VALUES))
+                                                .displayType(WidgetDisplayType.LINE)))))));
+
+    try {
+      Dashboard result = apiInstance.createDashboard(body);
+      System.out.println(result);
+    } catch (ApiException e) {
+      System.err.println("Exception when calling DashboardsApi#createDashboard");
+      System.err.println("Status code: " + e.getCode());
+      System.err.println("Reason: " + e.getResponseBody());
+      System.err.println("Response headers: " + e.getResponseHeaders());
+      e.printStackTrace();
+    }
+  }
+}

examples/v1/dashboards/CreateDashboard_3631423980.java

@@ -0,0 +1,57 @@
+// Create a new dashboard with timeseries widget without order_by for backward compatibility
+
+import com.datadog.api.client.ApiClient;
+import com.datadog.api.client.ApiException;
+import com.datadog.api.client.v1.api.DashboardsApi;
+import com.datadog.api.client.v1.model.Dashboard;
+import com.datadog.api.client.v1.model.DashboardLayoutType;
+import com.datadog.api.client.v1.model.TimeseriesWidgetDefinition;
+import com.datadog.api.client.v1.model.TimeseriesWidgetDefinitionType;
+import com.datadog.api.client.v1.model.TimeseriesWidgetRequest;
+import com.datadog.api.client.v1.model.Widget;
+import com.datadog.api.client.v1.model.WidgetDefinition;
+import com.datadog.api.client.v1.model.WidgetDisplayType;
+import com.datadog.api.client.v1.model.WidgetLineType;
+import com.datadog.api.client.v1.model.WidgetLineWidth;
+import com.datadog.api.client.v1.model.WidgetRequestStyle;
+import java.util.Collections;
+
+public class Example {
+  public static void main(String[] args) {
+    ApiClient defaultClient = ApiClient.getDefaultApiClient();
+    DashboardsApi apiInstance = new DashboardsApi(defaultClient);
+
+    Dashboard body =
+        new Dashboard()
+            .layoutType(DashboardLayoutType.ORDERED)
+            .title("Example-Dashboard without order_by")
+            .widgets(
+                Collections.singletonList(
+                    new Widget()
+                        .definition(
+                            new WidgetDefinition(
+                                new TimeseriesWidgetDefinition()
+                                    .type(TimeseriesWidgetDefinitionType.TIMESERIES)
+                                    .requests(
+                                        Collections.singletonList(
+                                            new TimeseriesWidgetRequest()
+                                                .q("avg:system.cpu.user{*} by {host}")
+                                                .style(
+                                                    new WidgetRequestStyle()
+                                                        .palette("dog_classic")
+                                                        .lineType(WidgetLineType.SOLID)
+                                                        .lineWidth(WidgetLineWidth.NORMAL))
+                                                .displayType(WidgetDisplayType.LINE)))))));
+
+    try {
+      Dashboard result = apiInstance.createDashboard(body);
+      System.out.println(result);
+    } catch (ApiException e) {
+      System.err.println("Exception when calling DashboardsApi#createDashboard");
+      System.err.println("Status code: " + e.getCode());
+      System.err.println("Reason: " + e.getResponseBody());
+      System.err.println("Response headers: " + e.getResponseHeaders());
+      e.printStackTrace();
+    }
+  }
+}

examples/v1/dashboards/CreateDashboard_416487533.java

@@ -0,0 +1,55 @@
+// Create a new dashboard with timeseries widget using order_by tags
+
+import com.datadog.api.client.ApiClient;
+import com.datadog.api.client.ApiException;
+import com.datadog.api.client.v1.api.DashboardsApi;
+import com.datadog.api.client.v1.model.Dashboard;
+import com.datadog.api.client.v1.model.DashboardLayoutType;
+import com.datadog.api.client.v1.model.TimeseriesWidgetDefinition;
+import com.datadog.api.client.v1.model.TimeseriesWidgetDefinitionType;
+import com.datadog.api.client.v1.model.TimeseriesWidgetRequest;
+import com.datadog.api.client.v1.model.Widget;
+import com.datadog.api.client.v1.model.WidgetDefinition;
+import com.datadog.api.client.v1.model.WidgetDisplayType;
+import com.datadog.api.client.v1.model.WidgetRequestStyle;
+import com.datadog.api.client.v1.model.WidgetStyleOrderBy;
+import java.util.Collections;
+
+public class Example {
+  public static void main(String[] args) {
+    ApiClient defaultClient = ApiClient.getDefaultApiClient();
+    DashboardsApi apiInstance = new DashboardsApi(defaultClient);
+
+    Dashboard body =
+        new Dashboard()
+            .layoutType(DashboardLayoutType.ORDERED)
+            .title("Example-Dashboard with order_by tags")
+            .widgets(
+                Collections.singletonList(
+                    new Widget()
+                        .definition(
+                            new WidgetDefinition(
+                                new TimeseriesWidgetDefinition()
+                                    .type(TimeseriesWidgetDefinitionType.TIMESERIES)
+                                    .requests(
+                                        Collections.singletonList(
+                                            new TimeseriesWidgetRequest()
+                                                .q("avg:system.cpu.user{*} by {host}")
+                                                .style(
+                                                    new WidgetRequestStyle()
+                                                        .palette("dog_classic")
+                                                        .orderBy(WidgetStyleOrderBy.TAGS))
+                                                .displayType(WidgetDisplayType.LINE)))))));
+
+    try {
+      Dashboard result = apiInstance.createDashboard(body);
+      System.out.println(result);
+    } catch (ApiException e) {
+      System.err.println("Exception when calling DashboardsApi#createDashboard");
+      System.err.println("Status code: " + e.getCode());
+      System.err.println("Reason: " + e.getResponseBody());
+      System.err.println("Response headers: " + e.getResponseHeaders());
+      e.printStackTrace();
+    }
+  }
+}

src/main/java/com/datadog/api/client/v1/model/WidgetRequestStyle.java

@@ -20,6 +20,7 @@
 @JsonPropertyOrder({
   WidgetRequestStyle.JSON_PROPERTY_LINE_TYPE,
   WidgetRequestStyle.JSON_PROPERTY_LINE_WIDTH,
+  WidgetRequestStyle.JSON_PROPERTY_ORDER_BY,
   WidgetRequestStyle.JSON_PROPERTY_PALETTE
 })
 @jakarta.annotation.Generated(
@@ -32,6 +33,9 @@ public class WidgetRequestStyle {
   public static final String JSON_PROPERTY_LINE_WIDTH = "line_width";
   private WidgetLineWidth lineWidth;
 
+  public static final String JSON_PROPERTY_ORDER_BY = "order_by";
+  private WidgetStyleOrderBy orderBy;
+
   public static final String JSON_PROPERTY_PALETTE = "palette";
   private String palette;
 
@@ -85,6 +89,33 @@ public void setLineWidth(WidgetLineWidth lineWidth) {
     this.lineWidth = lineWidth;
   }
 
+  public WidgetRequestStyle orderBy(WidgetStyleOrderBy orderBy) {
+    this.orderBy = orderBy;
+    this.unparsed |= !orderBy.isValid();
+    return this;
+  }
+
+  /**
+   * How to order series in timeseries visualizations. - <code>tags</code>: Order series
+   * alphabetically by tag name (default behavior) - <code>values</code>: Order series by their
+   * current metric values (typically descending)
+   *
+   * @return orderBy
+   */
+  @jakarta.annotation.Nullable
+  @JsonProperty(JSON_PROPERTY_ORDER_BY)
+  @JsonInclude(value = JsonInclude.Include.USE_DEFAULTS)
+  public WidgetStyleOrderBy getOrderBy() {
+    return orderBy;
+  }
+
+  public void setOrderBy(WidgetStyleOrderBy orderBy) {
+    if (!orderBy.isValid()) {
+      this.unparsed = true;
+    }
+    this.orderBy = orderBy;
+  }
+
   public WidgetRequestStyle palette(String palette) {
     this.palette = palette;
     return this;
@@ -164,13 +195,14 @@ public boolean equals(Object o) {
     WidgetRequestStyle widgetRequestStyle = (WidgetRequestStyle) o;
     return Objects.equals(this.lineType, widgetRequestStyle.lineType)
         && Objects.equals(this.lineWidth, widgetRequestStyle.lineWidth)
+        && Objects.equals(this.orderBy, widgetRequestStyle.orderBy)
         && Objects.equals(this.palette, widgetRequestStyle.palette)
         && Objects.equals(this.additionalProperties, widgetRequestStyle.additionalProperties);
   }
 
   @Override
   public int hashCode() {
-    return Objects.hash(lineType, lineWidth, palette, additionalProperties);
+    return Objects.hash(lineType, lineWidth, orderBy, palette, additionalProperties);
   }
 
   @Override
@@ -179,6 +211,7 @@ public String toString() {
     sb.append("class WidgetRequestStyle {\n");
     sb.append("    lineType: ").append(toIndentedString(lineType)).append("\n");
     sb.append("    lineWidth: ").append(toIndentedString(lineWidth)).append("\n");
+    sb.append("    orderBy: ").append(toIndentedString(orderBy)).append("\n");
     sb.append("    palette: ").append(toIndentedString(palette)).append("\n");
     sb.append("    additionalProperties: ")
         .append(toIndentedString(additionalProperties))

src/main/java/com/datadog/api/client/v1/model/WidgetStyleOrderBy.java

@@ -0,0 +1,59 @@
+/*
+ * 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.
+ */
+
+package com.datadog.api.client.v1.model;
+
+import com.datadog.api.client.ModelEnum;
+import com.fasterxml.jackson.annotation.JsonCreator;
+import com.fasterxml.jackson.core.JsonGenerator;
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.databind.SerializerProvider;
+import com.fasterxml.jackson.databind.annotation.JsonSerialize;
+import com.fasterxml.jackson.databind.ser.std.StdSerializer;
+import java.io.IOException;
+import java.util.Arrays;
+import java.util.HashSet;
+import java.util.Set;
+
+/**
+ * How to order series in timeseries visualizations. - <code>tags</code>: Order series
+ * alphabetically by tag name (default behavior) - <code>values</code>: Order series by their
+ * current metric values (typically descending)
+ */
+@JsonSerialize(using = WidgetStyleOrderBy.WidgetStyleOrderBySerializer.class)
+public class WidgetStyleOrderBy extends ModelEnum<String> {
+
+  private static final Set<String> allowedValues =
+      new HashSet<String>(Arrays.asList("tags", "values"));
+
+  public static final WidgetStyleOrderBy TAGS = new WidgetStyleOrderBy("tags");
+  public static final WidgetStyleOrderBy VALUES = new WidgetStyleOrderBy("values");
+
+  WidgetStyleOrderBy(String value) {
+    super(value, allowedValues);
+  }
+
+  public static class WidgetStyleOrderBySerializer extends StdSerializer<WidgetStyleOrderBy> {
+    public WidgetStyleOrderBySerializer(Class<WidgetStyleOrderBy> t) {
+      super(t);
+    }
+
+    public WidgetStyleOrderBySerializer() {
+      this(null);
+    }
+
+    @Override
+    public void serialize(WidgetStyleOrderBy value, JsonGenerator jgen, SerializerProvider provider)
+        throws IOException, JsonProcessingException {
+      jgen.writeObject(value.value);
+    }
+  }
+
+  @JsonCreator
+  public static WidgetStyleOrderBy fromValue(String value) {
+    return new WidgetStyleOrderBy(value);
+  }
+}

src/test/resources/cassettes/features/v1/Create_a_new_dashboard_with_timeseries_widget_using_order_by_tags.freeze

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

src/test/resources/cassettes/features/v1/Create_a_new_dashboard_with_timeseries_widget_using_order_by_tags.json

@@ -0,0 +1,58 @@
+[
+  {
+    "httpRequest": {
+      "body": {
+        "type": "JSON",
+        "json": "{\"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": {},
+      "method": "POST",
+      "path": "/api/v1/dashboard",
+      "keepAlive": false,
+      "secure": true
+    },
+    "httpResponse": {
+      "body": "{\"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"
+        ]
+      },
+      "statusCode": 200,
+      "reasonPhrase": "OK"
+    },
+    "times": {
+      "remainingTimes": 1
+    },
+    "timeToLive": {
+      "unlimited": true
+    },
+    "id": "abeac4e0-5184-00e1-9b5a-81838f265016"
+  },
+  {
+    "httpRequest": {
+      "headers": {},
+      "method": "DELETE",
+      "path": "/api/v1/dashboard/2r3-a4g-ubz",
+      "keepAlive": false,
+      "secure": true
+    },
+    "httpResponse": {
+      "body": "{\"deleted_dashboard_id\":\"2r3-a4g-ubz\"}",
+      "headers": {
+        "Content-Type": [
+          "application/json"
+        ]
+      },
+      "statusCode": 200,
+      "reasonPhrase": "OK"
+    },
+    "times": {
+      "remainingTimes": 1
+    },
+    "timeToLive": {
+      "unlimited": true
+    },
+    "id": "b2a45bba-7e7d-6dd1-c196-6614f1adfe42"
+  }
+]