Expose monthly resource usage in the public API

.generator/schemas/v2/openapi.yaml

@@ -90741,6 +90741,85 @@ components:
         meta:
           $ref: "#/components/schemas/MonthlyCostAttributionMeta"
       type: object
+    MonthlyResource:
+      description: A resource's usage for the requested billing dimension and month.
+      properties:
+        attributes:
+          $ref: "#/components/schemas/MonthlyResourceAttributes"
+        id:
+          description: Identifier for the resource usage record. Treat this value as opaque.
+          type: string
+        type:
+          $ref: "#/components/schemas/MonthlyResourceType"
+      type: object
+    MonthlyResourceAttributes:
+      description: Resource usage and organization details for the requested month.
+      properties:
+        data_date:
+          description: Date of the source usage data. May be empty when unavailable.
+          type: string
+        org_name:
+          description: Name of the organization that owns the resource.
+          type: string
+        public_id:
+          description: Public ID of the organization that owns the resource.
+          type: string
+        resource_name:
+          description: Name of the resource, such as a host name, metric name, or log index.
+          type: string
+        resource_type:
+          description: Usage type of the resource. Values depend on the billing dimension and are not limited to host types.
+          type: string
+        tags:
+          additionalProperties:
+            type: string
+          description: Resource tags when available. Empty for resource types without tag data.
+          type: object
+        timestamp:
+          description: Selected billing hour for percentile usage, or the first day of the month for monthly usage. May be empty when unavailable.
+          type: string
+        usage_value:
+          description: Usage attributed to the resource in the units of the requested billing dimension. Values can be fractional.
+          format: double
+          nullable: true
+          type: number
+      type: object
+    MonthlyResourceType:
+      default: monthly_resource
+      description: Type of a monthly resource usage record.
+      enum:
+        - monthly_resource
+      type: string
+      x-enum-varnames:
+        - MONTHLY_RESOURCE
+    MonthlyResourcesMetadata:
+      description: Metadata for monthly resource usage.
+      properties:
+        pagination:
+          $ref: "#/components/schemas/MonthlyResourcesPagination"
+      type: object
+    MonthlyResourcesPagination:
+      description: Pagination information for monthly resource usage.
+      properties:
+        next_record_id:
+          description: Cursor for the next request. Pass as `page[next_record_id]` with the same filters. Null when there are no more results.
+          nullable: true
+          type: string
+        sort_direction:
+          description: Direction used to order the results, either `ASC` or `DESC`. Ordering depends on the billing dimension.
+          type: string
+      type: object
+    MonthlyResourcesResponse:
+      description: Monthly usage for host and non-host resources.
+      properties:
+        data:
+          description: Resource usage records. Empty when no matching resources are available.
+          items:
+            $ref: "#/components/schemas/MonthlyResource"
+          type: array
+        meta:
+          $ref: "#/components/schemas/MonthlyResourcesMetadata"
+      type: object
     MuteDataType:
       default: mute
       description: Mute resource type.
@@ -268603,6 +268682,154 @@ paths:
         operator: OR
         permissions:
           - usage_read
+  /api/v2/usage/monthly_resources:
+    get:
+      description: |-
+        Get resource-level usage for a billing dimension and month, using the same
+        data as the resource breakdown in Plan & Usage. Supports all host and
+        non-host resource types available in that breakdown. Availability depends
+        on the billing dimension and the organization's usage data.
+
+        Results are scoped to the authenticated organization. Set `filter[include_descendants]`
+        to `true` to also return usage from its descendant organizations in all regions.
+
+        Set `filter[view]` to `billable` to return resources that contribute to billable usage.
+        For dimensions billed at the 99th percentile, this view returns resources at the
+        selected billing hour. For sum-based dimensions, it returns monthly resource usage.
+        Set `filter[view]` to `all` to return the full monthly resource breakdown. Requests
+        for unsupported billing dimensions, or dimensions configured with an unsupported
+        billing aggregation method, return a `400 Bad Request` error.
+
+        To get the next page of results, pass the `meta.pagination.next_record_id` value
+        from the previous response as `page[next_record_id]`, and keep all filters unchanged.
+        A null cursor indicates the last page. Each response contains at most `page[limit]`
+        resource records. This limit applies to all queries, including billable queries and
+        queries across descendant organizations.
+      operationId: GetUsageMonthlyResources
+      parameters:
+        - description: Billing dimension to retrieve, such as `infra_host`, `indexed_points`, or `logs_indexed_30day`.
+          example: infra_host
+          in: query
+          name: filter[billing_dimension]
+          required: true
+          schema:
+            type: string
+        - description: Month of usage to retrieve in `YYYY-MM` format.
+          example: "2026-04"
+          in: query
+          name: filter[month]
+          required: true
+          schema:
+            type: string
+        - description: |-
+            Set to `billable` to return resources that contribute to billable usage, or `all`
+            to return the full monthly resource breakdown.
+          example: billable
+          in: query
+          name: filter[view]
+          required: true
+          schema:
+            type: string
+        - description: Include usage for descendant organizations of the authenticated organization.
+          in: query
+          name: filter[include_descendants]
+          required: false
+          schema:
+            default: false
+            type: boolean
+        - description: |-
+            Maximum number of resource records per response. Must be a positive integer.
+            Values above 100,000 are capped at 100,000.
+          in: query
+          name: page[limit]
+          required: false
+          schema:
+            default: 100000
+            format: int64
+            maximum: 100000
+            minimum: 1
+            type: integer
+        - description: Opaque cursor from `meta.pagination.next_record_id` in the previous response. Omit for the first request.
+          in: query
+          name: page[next_record_id]
+          required: false
+          schema:
+            type: string
+      responses:
+        "200":
+          content:
+            application/json;datetime-format=rfc3339:
+              examples:
+                default:
+                  value:
+                    data:
+                      - attributes:
+                          data_date: "2026-04-30"
+                          org_name: Example organization
+                          public_id: abc123
+                          resource_name: host-1.prod
+                          resource_type: agent
+                          tags:
+                            env: prod
+                          timestamp: "2026-04-22 16:00:00+00:00"
+                          usage_value: 1
+                        id: abc123_agent_host-1.prod
+                        type: monthly_resource
+                    meta:
+                      pagination:
+                        next_record_id:
+                        sort_direction: ASC
+                non_host:
+                  value:
+                    data:
+                      - attributes:
+                          data_date: "2026-04-30"
+                          org_name: Example organization
+                          public_id: abc123
+                          resource_name: app.requests
+                          resource_type: post_threshold_indexed
+                          tags: {}
+                          timestamp: "2026-04-01"
+                          usage_value: 1250.5
+                        id: abc123_post_threshold_indexed_app.requests
+                        type: monthly_resource
+                    meta:
+                      pagination:
+                        next_record_id:
+                        sort_direction: DESC
+              schema:
+                $ref: "#/components/schemas/MonthlyResourcesResponse"
+          description: OK
+        "400":
+          content:
+            application/json;datetime-format=rfc3339:
+              schema:
+                $ref: "#/components/schemas/JSONAPIErrorResponse"
+          description: Bad Request
+        "403":
+          content:
+            application/json;datetime-format=rfc3339:
+              schema:
+                $ref: "#/components/schemas/APIErrorResponse"
+          description: Forbidden - User is not authorized
+        "429":
+          content:
+            application/json;datetime-format=rfc3339:
+              schema:
+                $ref: "#/components/schemas/APIErrorResponse"
+          description: Too many requests
+      security:
+        - apiKeyAuth: []
+          appKeyAuth: []
+        - AuthZ:
+            - usage_read
+      summary: Get monthly usage by resource
+      tags:
+        - Usage Metering
+      "x-permission":
+        operator: OR
+        permissions:
+          - usage_read
   /api/v2/usage/observability_pipelines:
     get:
       deprecated: true

examples/v2/usage-metering/GetUsageMonthlyResources.java

@@ -0,0 +1,31 @@
+// Get monthly usage by resource returns "OK" response
+
+import com.datadog.api.client.ApiClient;
+import com.datadog.api.client.ApiException;
+import com.datadog.api.client.v2.api.UsageMeteringApi;
+import com.datadog.api.client.v2.api.UsageMeteringApi.GetUsageMonthlyResourcesOptionalParameters;
+import com.datadog.api.client.v2.model.MonthlyResourcesResponse;
+
+public class Example {
+  public static void main(String[] args) {
+    ApiClient defaultClient = ApiClient.getDefaultApiClient();
+    defaultClient.setAccessToken(System.getenv("DD_BEARER_TOKEN"));
+    UsageMeteringApi apiInstance = new UsageMeteringApi(defaultClient);
+
+    try {
+      MonthlyResourcesResponse result =
+          apiInstance.getUsageMonthlyResources(
+              "infra_host",
+              "2026-04",
+              "all",
+              new GetUsageMonthlyResourcesOptionalParameters().pageLimit(1L));
+      System.out.println(result);
+    } catch (ApiException e) {
+      System.err.println("Exception when calling UsageMeteringApi#getUsageMonthlyResources");
+      System.err.println("Status code: " + e.getCode());
+      System.err.println("Reason: " + e.getResponseBody());
+      System.err.println("Response headers: " + e.getResponseHeaders());
+      e.printStackTrace();
+    }
+  }
+}

examples/v2/usage-metering/GetUsageMonthlyResources_1935480325.java

@@ -0,0 +1,31 @@
+// Get monthly usage by resource supports non-host resources
+
+import com.datadog.api.client.ApiClient;
+import com.datadog.api.client.ApiException;
+import com.datadog.api.client.v2.api.UsageMeteringApi;
+import com.datadog.api.client.v2.api.UsageMeteringApi.GetUsageMonthlyResourcesOptionalParameters;
+import com.datadog.api.client.v2.model.MonthlyResourcesResponse;
+
+public class Example {
+  public static void main(String[] args) {
+    ApiClient defaultClient = ApiClient.getDefaultApiClient();
+    defaultClient.setAccessToken(System.getenv("DD_BEARER_TOKEN"));
+    UsageMeteringApi apiInstance = new UsageMeteringApi(defaultClient);
+
+    try {
+      MonthlyResourcesResponse result =
+          apiInstance.getUsageMonthlyResources(
+              "indexed_points",
+              "2026-04",
+              "all",
+              new GetUsageMonthlyResourcesOptionalParameters().pageLimit(1L));
+      System.out.println(result);
+    } catch (ApiException e) {
+      System.err.println("Exception when calling UsageMeteringApi#getUsageMonthlyResources");
+      System.err.println("Status code: " + e.getCode());
+      System.err.println("Reason: " + e.getResponseBody());
+      System.err.println("Response headers: " + e.getResponseHeaders());
+      e.printStackTrace();
+    }
+  }
+}