Clarify Containers API filtering, grouping, and pagination

.generator/schemas/v2/openapi.yaml

@@ -22459,7 +22459,9 @@ components:
           $ref: "#/components/schemas/ContainerType"
       type: object
     ContainerAttributes:
-      description: Attributes for a container.
+      description: |-
+        Attributes for a container. For CPU or memory metrics, use its full `container_id` as
+        `container_id:<container_id>` in `tag_filters` with the `container` data source.
       properties:
         container_id:
           description: The ID of the container.
@@ -22526,7 +22528,8 @@ components:
       description: Attributes for a container group.
       properties:
         count:
-          description: Number of containers in the group.
+          description: >-
+            Number of containers in the group. A container with multiple values for a grouping tag can appear in multiple groups. Summing group counts can overcount distinct containers.
           format: int64
           type: integer
         tags:
@@ -22540,7 +22543,10 @@ components:
           $ref: "#/components/schemas/ContainerGroupRelationshipsLink"
       type: object
     ContainerGroupRelationshipsData:
-      description: Links data.
+      description: |-
+        This array is always empty, even when the group includes containers. To retrieve the containers
+        in this group, make a new request to this endpoint with the `filter[tags]` value from
+        `links.related`, using your site's API host.
       items:
         description: A link data.
         type: string
@@ -22892,20 +22898,22 @@ components:
           description: The cursor used to get the current results, if any.
           type: string
         limit:
-          description: Number of results returned
+          description: Maximum number of results requested.
           format: int32
           maximum: 10000
           minimum: 0
           type: integer
         next_cursor:
-          description: The cursor used to get the next results, if any.
+          description: |-
+            The cursor used to get the next results, if any. To make the next request, use the same
+            parameters with the addition of the `page[cursor]`. Empty for grouped results.
           type: string
         prev_cursor:
           description: The cursor used to get the previous results, if any.
           nullable: true
           type: string
         total:
-          description: Total number of records that match the query.
+          description: Total number of containers that match the query. Always `0` for grouped results.
           format: int64
           type: integer
         type:
@@ -23013,7 +23021,7 @@ components:
       description: List of containers.
       properties:
         data:
-          description: Array of Container objects.
+          description: Array of containers or container group objects.
           items:
             $ref: "#/components/schemas/ContainerItem"
           type: array
@@ -158303,31 +158311,49 @@ paths:
         permissions: []
   /api/v2/containers:
     get:
-      description: Get all containers for your organization.
+      description: |-
+        Get all containers for your organization. Use `group_by` to return container groups with counts.
+        Grouped results are limited by `page[size]` and do not support pagination.
+
+        To get CPU or memory metrics, use a `container` data source query with `/api/v2/query/scalar`
+        or `/api/v2/query/timeseries`.
       operationId: ListContainers
       parameters:
-        - description: Comma-separated list of tags to filter containers by.
+        - description: |-
+            Comma-separated `key:value` tags. A container must match every tag. Wildcards, negation
+            (`-key:value`), spaces, and `IN (...)` are not supported. To cover several hosts, make one
+            request per host.
           example: env:prod,short_image:cassandra
           in: query
           name: filter[tags]
           required: false
           schema:
             type: string
-        - description: Comma-separated list of tags to group containers by.
+        - description: |-
+            Comma-separated list of up to three tag keys to group containers by. Returns `container_group`
+            objects with counts and tags. Grouped results ignore `sort` and do not support pagination.
+            Containers with multiple values for a grouping tag can appear in multiple groups.
+            Summing group counts can overcount distinct containers.
           example: datacenter,cluster
           in: query
           name: group_by
           required: false
           schema:
             type: string
-        - description: Attribute to sort containers by.
+        - description: |-
+            Attribute to sort individual containers by: `name`, `created_at`, `started_at`, `state`,
+            `container_id`, `host`, `image_name`, or `image_digest`. Defaults to `started_at` in ascending
+            order. Prefix the attribute with `-` for descending order, such as `-started_at`.
+            Ignored when `group_by` is specified.
           example: started_at
           in: query
           name: sort
           required: false
           schema:
             type: string
-        - description: Maximum number of results returned.
+        - description: |-
+            Maximum number of results returned. For grouped results, defaults to `100` with a maximum
+            of `1000` groups.
           in: query
           name: page[size]
           required: false
@@ -158366,6 +158392,27 @@ paths:
                         limit: 1000
                         total: 1
                         type: cursor_limit
+                grouped:
+                  summary: Containers grouped by short_image
+                  value:
+                    data:
+                      - attributes:
+                          count: 3
+                          tags:
+                            short_image: nginx
+                        id: short_image:nginx
+                        relationships:
+                          containers:
+                            data: []
+                            links:
+                              related: https://api.datadoghq.com/api/v2/containers?filter[tags]=short_image:nginx
+                        type: container_group
+                    meta:
+                      pagination:
+                        limit: 100
+                        next_cursor: ""
+                        total: 0
+                        type: cursor_limit
               schema:
                 $ref: "#/components/schemas/ContainersResponse"
           description: OK
@@ -255202,7 +255249,8 @@ tags:
       The Container Images API allows you to query Container Image data for your organization. See the [Container Images View page](https://docs.datadoghq.com/infrastructure/containers/container_images/) for more information.
     name: Container Images
   - description: |-
-      The Containers API allows you to query container data for your organization. See the [Container Monitoring page](https://docs.datadoghq.com/containers/) for more information.
+      The Containers API allows you to query container data for your organization.
+      See the [Container Monitoring page](https://docs.datadoghq.com/containers/) for more information.
     name: Containers
   - description: |-
       Programmatic management of a customer's Datadog organization. Use this API to perform

src/main/java/com/datadog/api/client/v2/api/ContainersApi.java

@@ -58,7 +58,9 @@ public static class ListContainersOptionalParameters {
     /**
      * Set filterTags.
      *
-     * @param filterTags Comma-separated list of tags to filter containers by. (optional)
+     * @param filterTags Comma-separated <code>key:value</code> tags. A container must match every
+     *     tag. Wildcards, negation (<code>-key:value</code>), spaces, and <code>IN (...)</code> are
+     *     not supported. To cover several hosts, make one request per host. (optional)
      * @return ListContainersOptionalParameters
      */
     public ListContainersOptionalParameters filterTags(String filterTags) {
@@ -69,7 +71,11 @@ public ListContainersOptionalParameters filterTags(String filterTags) {
     /**
      * Set groupBy.
      *
-     * @param groupBy Comma-separated list of tags to group containers by. (optional)
+     * @param groupBy Comma-separated list of up to three tag keys to group containers by. Returns
+     *     <code>container_group</code> objects with counts and tags. Grouped results ignore <code>
+     *     sort</code> and do not support pagination. Containers with multiple values for a grouping
+     *     tag can appear in multiple groups. Summing group counts can overcount distinct
+     *     containers. (optional)
      * @return ListContainersOptionalParameters
      */
     public ListContainersOptionalParameters groupBy(String groupBy) {
@@ -80,7 +86,12 @@ public ListContainersOptionalParameters groupBy(String groupBy) {
     /**
      * Set sort.
      *
-     * @param sort Attribute to sort containers by. (optional)
+     * @param sort Attribute to sort individual containers by: <code>name</code>, <code>created_at
+     *     </code>, <code>started_at</code>, <code>state</code>, <code>container_id</code>, <code>
+     *     host</code>, <code>image_name</code>, or <code>image_digest</code>. Defaults to <code>
+     *     started_at</code> in ascending order. Prefix the attribute with <code>-</code> for
+     *     descending order, such as <code>-started_at</code>. Ignored when <code>group_by</code> is
+     *     specified. (optional)
      * @return ListContainersOptionalParameters
      */
     public ListContainersOptionalParameters sort(String sort) {
@@ -91,7 +102,8 @@ public ListContainersOptionalParameters sort(String sort) {
     /**
      * Set pageSize.
      *
-     * @param pageSize Maximum number of results returned. (optional, default to 1000)
+     * @param pageSize Maximum number of results returned. For grouped results, defaults to <code>
+     *     100</code> with a maximum of <code>1000</code> groups. (optional, default to 1000)
      * @return ListContainersOptionalParameters
      */
     public ListContainersOptionalParameters pageSize(Integer pageSize) {
@@ -225,7 +237,12 @@ public PaginationIterable<ContainerItem> listContainersWithPagination(
   }
 
   /**
-   * Get all containers for your organization.
+   * Get all containers for your organization. Use <code>group_by</code> to return container groups
+   * with counts. Grouped results are limited by <code>page[size]</code> and do not support
+   * pagination.
+   *
+   * <p>To get CPU or memory metrics, use a <code>container</code> data source query with <code>
+   * /api/v2/query/scalar</code> or <code>/api/v2/query/timeseries</code>.
    *
    * @param parameters Optional parameters for the request.
    * @return ApiResponse&lt;ContainersResponse&gt;

src/main/java/com/datadog/api/client/v2/model/Container.java

@@ -42,7 +42,9 @@ public Container attributes(ContainerAttributes attributes) {
   }
 
   /**
-   * Attributes for a container.
+   * Attributes for a container. For CPU or memory metrics, use its full <code>container_id</code>
+   * as <code>container_id:&lt;container_id&gt;</code> in <code>tag_filters</code> with the <code>
+   * container</code> data source.
    *
    * @return attributes
    */

src/main/java/com/datadog/api/client/v2/model/ContainerAttributes.java

@@ -19,7 +19,11 @@
 import java.util.Objects;
 import org.openapitools.jackson.nullable.JsonNullable;
 
-/** Attributes for a container. */
+/**
+ * Attributes for a container. For CPU or memory metrics, use its full <code>container_id</code> as
+ * <code>container_id:&lt;container_id&gt;</code> in <code>tag_filters</code> with the <code>
+ * container</code> data source.
+ */
 @JsonPropertyOrder({
   ContainerAttributes.JSON_PROPERTY_CONTAINER_ID,
   ContainerAttributes.JSON_PROPERTY_CREATED_AT,

src/main/java/com/datadog/api/client/v2/model/ContainerGroupAttributes.java

@@ -37,7 +37,8 @@ public ContainerGroupAttributes count(Long count) {
   }
 
   /**
-   * Number of containers in the group.
+   * Number of containers in the group. A container with multiple values for a grouping tag can
+   * appear in multiple groups. Summing group counts can overcount distinct containers.
    *
    * @return count
    */

src/main/java/com/datadog/api/client/v2/model/ContainerGroupRelationshipsLink.java

@@ -47,7 +47,9 @@ public ContainerGroupRelationshipsLink addDataItem(String dataItem) {
   }
 
   /**
-   * Links data.
+   * This array is always empty, even when the group includes containers. To retrieve the containers
+   * in this group, make a new request to this endpoint with the <code>filter[tags]</code> value
+   * from <code>links.related</code>, using your site's API host.
    *
    * @return data
    */

src/main/java/com/datadog/api/client/v2/model/ContainerMetaPage.java

@@ -75,7 +75,7 @@ public ContainerMetaPage limit(Integer limit) {
   }
 
   /**
-   * Number of results returned minimum: 0 maximum: 10000
+   * Maximum number of results requested. minimum: 0 maximum: 10000
    *
    * @return limit
    */
@@ -96,7 +96,8 @@ public ContainerMetaPage nextCursor(String nextCursor) {
   }
 
   /**
-   * The cursor used to get the next results, if any.
+   * The cursor used to get the next results, if any. To make the next request, use the same
+   * parameters with the addition of the <code>page[cursor]</code>. Empty for grouped results.
    *
    * @return nextCursor
    */
@@ -148,7 +149,7 @@ public ContainerMetaPage total(Long total) {
   }
 
   /**
-   * Total number of records that match the query.
+   * Total number of containers that match the query. Always <code>0</code> for grouped results.
    *
    * @return total
    */

src/main/java/com/datadog/api/client/v2/model/ContainersResponse.java

@@ -57,7 +57,7 @@ public ContainersResponse addDataItem(ContainerItem dataItem) {
   }
 
   /**
-   * Array of Container objects.
+   * Array of containers or container group objects.
    *
    * @return data
    */