Clarify additionalProperties note is SDK-only; add per-language access patterns

data/api/v1/full_spec.yaml

@@ -23021,10 +23021,11 @@ components:
       description: |-
         Response with hourly report of all data billed by Datadog for all organizations.
 
-        Newly added billing dimensions and usage types appear as untyped keys on the
-        `additionalProperties` map instead of as typed fields. Call
-        `GET /api/v2/usage/summary/available_fields` to enumerate every key returned
-        at this response level—both typed fields and `additionalProperties` keys.
+        For SDK users only: all fields at this response level are accessible through the
+        `additionalProperties` map. Existing typed-field getters are unchanged. New billing
+        dimensions will not have typed-field getters. Use
+        [Get available fields for usage summary](https://docs.datadoghq.com/api/latest/usage-metering/#get-usage-summary-available-fields)
+        to enumerate every available key.
       properties:
         agent_host_top99p:
           description: Shows the 99th percentile of all agent hosts over all hours in the current date for all organizations.
@@ -24323,10 +24324,11 @@ components:
       description: |-
         Global hourly report of all data billed by Datadog for a given organization.
 
-        Newly added billing dimensions and usage types appear as untyped keys on the
-        `additionalProperties` map instead of as typed fields. Call
-        `GET /api/v2/usage/summary/available_fields` to enumerate every key returned
-        at this response level—both typed fields and `additionalProperties` keys.
+        For SDK users only: all fields at this response level are accessible through the
+        `additionalProperties` map. Existing typed-field getters are unchanged. New billing
+        dimensions will not have typed-field getters. Use
+        [Get available fields for usage summary](https://docs.datadoghq.com/api/latest/usage-metering/#get-usage-summary-available-fields)
+        to enumerate every available key.
       properties:
         account_name:
           description: The account name.
@@ -25644,10 +25646,11 @@ components:
         Response summarizing all usage aggregated across the months in the request for
         all organizations, and broken down by month and by organization.
 
-        Newly added billing dimensions and usage types appear as untyped keys on the
-        `additionalProperties` map instead of as typed fields. Call
-        `GET /api/v2/usage/summary/available_fields` to enumerate every key returned
-        at this response level—both typed fields and `additionalProperties` keys.
+        For SDK users only: all fields at this response level are accessible through the
+        `additionalProperties` map. Existing typed-field getters are unchanged. New billing
+        dimensions will not have typed-field getters. Use
+        [Get available fields for usage summary](https://docs.datadoghq.com/api/latest/usage-metering/#get-usage-summary-available-fields)
+        to enumerate every available key.
       properties:
         agent_host_top99p_sum:
           description: Shows the 99th percentile of all agent hosts over all hours in the current month for all organizations.
@@ -44544,11 +44547,12 @@ paths:
       description: |-
         Get all usage across your account.
 
-        Newly added billing dimensions and usage types appear as untyped keys on the
-        `additionalProperties` map of `UsageSummaryResponse`, `UsageSummaryDate`, and
-        `UsageSummaryDateOrg` instead of as typed fields. Call
-        `GET /api/v2/usage/summary/available_fields` to enumerate every key returned
-        at each response level—both typed fields and `additionalProperties` keys.
+        For SDK users only: all fields on `UsageSummaryResponse`, `UsageSummaryDate`, and
+        `UsageSummaryDateOrg` are accessible through each object's `additionalProperties` map.
+        Existing typed-field getters are unchanged. New billing dimensions will not have
+        typed-field getters. Use
+        [Get available fields for usage summary](https://docs.datadoghq.com/api/latest/usage-metering/#get-usage-summary-available-fields)
+        to enumerate every available key at each response level.
 
         This endpoint is only accessible for [parent-level organizations](https://docs.datadoghq.com/account_management/multi_organization/).
       operationId: GetUsageSummary

data/api/v1/translate_actions.json

@@ -1144,7 +1144,7 @@
     "summary": "Get hourly usage for SNMP devices"
   },
   "GetUsageSummary": {
-    "description": "Get all usage across your account.\n\nNewly added billing dimensions and usage types appear as untyped keys on the\n`additionalProperties` map of `UsageSummaryResponse`, `UsageSummaryDate`, and\n`UsageSummaryDateOrg` instead of as typed fields. Call\n`GET /api/v2/usage/summary/available_fields` to enumerate every key returned\nat each response level—both typed fields and `additionalProperties` keys.\n\nThis endpoint is only accessible for [parent-level organizations](https://docs.datadoghq.com/account_management/multi_organization/).",
+    "description": "Get all usage across your account.\n\nFor SDK users only: all fields on `UsageSummaryResponse`, `UsageSummaryDate`, and\n`UsageSummaryDateOrg` are accessible through each object's `additionalProperties` map.\nExisting typed-field getters are unchanged. New billing dimensions will not have\ntyped-field getters. Use\n[Get available fields for usage summary](https://docs.datadoghq.com/api/latest/usage-metering/#get-usage-summary-available-fields)\nto enumerate every available key at each response level.\n\nThis endpoint is only accessible for [parent-level organizations](https://docs.datadoghq.com/account_management/multi_organization/).",
     "summary": "Get usage across your account"
   },
   "GetUsageSynthetics": {

data/api/v2/full_spec.yaml

@@ -190713,6 +190713,37 @@ paths:
         dimensions and usage types added after the v1 schema freeze).
 
         This endpoint is only accessible for [parent-level organizations](https://docs.datadoghq.com/account_management/multi_organization/).
+
+        Go example:
+
+        ```go
+        fields, _, err := api.GetUsageSummaryAvailableFields(ctx)
+        attr := fields.Data.GetAttributes()
+
+        // resp is the *UsageSummaryResponse returned by api.GetUsageSummary(ctx, ...)
+        // Layer 1: UsageSummaryResponse
+        for _, key := range attr.GetResponseFields() {
+            if val, ok := resp.AdditionalProperties[key]; ok {
+                fmt.Println(key, val.(json.Number))
+            }
+        }
+        // Layer 2: UsageSummaryDate (per month)
+        for _, date := range resp.GetUsage() {
+            for _, key := range attr.GetDateFields() {
+                if val, ok := date.AdditionalProperties[key]; ok {
+                    fmt.Println(key, val.(json.Number))
+                }
+            }
+            // Layer 3: UsageSummaryDateOrg (per org per month)
+            for _, org := range date.GetOrgs() {
+                for _, key := range attr.GetDateOrgFields() {
+                    if val, ok := org.AdditionalProperties[key]; ok {
+                        fmt.Println(key, val.(json.Number))
+                    }
+                }
+            }
+        }
+        ```
       operationId: GetUsageSummaryAvailableFields
       responses:
         "200":

data/api/v2/translate_actions.json

@@ -6375,7 +6375,7 @@
     "summary": "Get projected cost across your account"
   },
   "GetUsageSummaryAvailableFields": {
-    "description": "List the field names returned by `GET /api/v1/usage/summary` at each of its\nthree response levels. Each list contains every key the data endpoint\nemits—both typed fields declared in the OpenAPI spec and untyped keys\nexposed through `additionalProperties` (the latter used for billing\ndimensions and usage types added after the v1 schema freeze).\n\nThis endpoint is only accessible for [parent-level organizations](https://docs.datadoghq.com/account_management/multi_organization/).",
+    "description": "List the field names returned by `GET /api/v1/usage/summary` at each of its\nthree response levels. Each list contains every key the data endpoint\nemits—both typed fields declared in the OpenAPI spec and untyped keys\nexposed through `additionalProperties` (the latter used for billing\ndimensions and usage types added after the v1 schema freeze).\n\nThis endpoint is only accessible for [parent-level organizations](https://docs.datadoghq.com/account_management/multi_organization/).\n\nGo example:\n\n```go\nfields, _, err := api.GetUsageSummaryAvailableFields(ctx)\nattr := fields.Data.GetAttributes()\n\n// resp is the *UsageSummaryResponse returned by api.GetUsageSummary(ctx, ...)\n// Layer 1: UsageSummaryResponse\nfor _, key := range attr.GetResponseFields() {\n    if val, ok := resp.AdditionalProperties[key]; ok {\n        fmt.Println(key, val.(json.Number))\n    }\n}\n// Layer 2: UsageSummaryDate (per month)\nfor _, date := range resp.GetUsage() {\n    for _, key := range attr.GetDateFields() {\n        if val, ok := date.AdditionalProperties[key]; ok {\n            fmt.Println(key, val.(json.Number))\n        }\n    }\n    // Layer 3: UsageSummaryDateOrg (per org per month)\n    for _, org := range date.GetOrgs() {\n        for _, key := range attr.GetDateOrgFields() {\n            if val, ok := org.AdditionalProperties[key]; ok {\n                fmt.Println(key, val.(json.Number))\n            }\n        }\n    }\n}\n```",
     "summary": "Get available fields for usage summary"
   },
   "GetUsageAttributionTypes": {