Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
243 changes: 243 additions & 0 deletions .generator/schemas/v2/openapi.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -92205,6 +92205,91 @@ 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
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_type:
description: Usage type of the resource. Values depend on the billing dimension and are not limited to host types.
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
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
MonthlyResourcesView:
description: Whether to return billable resources or the full monthly resource breakdown.
enum:
- billable
- all
type: string
x-enum-varnames:
- BILLABLE
- ALL
MuteDataType:
default: mute
description: Mute resource type.
Expand Down Expand Up @@ -270789,6 +270874,164 @@ 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. Paginated responses contain at most
`page[limit]` resource records, including queries across descendant organizations.

Exception: for any billing dimension billed at the 99th percentile,
`filter[view]=billable` returns the complete resource breakdown in one response,
including requested descendants. Eligibility depends on the organization's
billing configuration for the requested dimension and month, not on the product
name. For these queries, `page[limit]` and `page[next_record_id]` are ignored, and
`meta.pagination.next_record_id` is null. Sum-based usage and `filter[view]=all`
remain paginated.
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:
pattern: "^[0-9]{4}-(0[1-9]|1[0-2])$"
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:
$ref: "#/components/schemas/MonthlyResourcesView"
- 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 paginated response. Must be a positive integer.
Values above 100,000 are capped at 100,000. Ignored for billable queries using
99th-percentile billing, which return the complete result in one response.
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. Ignored for billable queries using 99th-percentile
billing, which always return the complete result.
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
tags:
env: prod
timestamp: "2026-04-22 16:00:00+00:00"
usage_type: agent
usage_value: 1
id: abc123_agent_host-1.prod
type: monthly_resource
meta:
pagination:
next_record_id:
non_host:
value:
data:
- attributes:
data_date: "2026-04-30"
org_name: Example organization
public_id: abc123
resource_name: app.requests
tags: {}
timestamp: "2026-04-01"
usage_type: post_threshold_indexed
usage_value: 1250.5
id: abc123_post_threshold_indexed_app.requests
type: monthly_resource
meta:
pagination:
next_record_id:
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/JSONAPIErrorResponse"
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
Expand Down
11 changes: 11 additions & 0 deletions examples/v2/usage-metering/GetUsageMonthlyResources.rb
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
# Get monthly usage by resource returns "OK" response

require "datadog_api_client"
DatadogAPIClient.configure do |config|
config.access_token = ENV["DD_BEARER_TOKEN"]
end
api_instance = DatadogAPIClient::V2::UsageMeteringAPI.new
opts = {
page_limit: 1,
}
p api_instance.get_usage_monthly_resources("infra_host", "2026-04", MonthlyResourcesView::ALL, opts)
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
# Get monthly usage by resource supports non-host resources

require "datadog_api_client"
DatadogAPIClient.configure do |config|
config.access_token = ENV["DD_BEARER_TOKEN"]
end
api_instance = DatadogAPIClient::V2::UsageMeteringAPI.new
opts = {
page_limit: 1,
}
p api_instance.get_usage_monthly_resources("indexed_points", "2026-04", MonthlyResourcesView::ALL, opts)
8 changes: 8 additions & 0 deletions features/scenarios_model_mapping.rb
Original file line number Diff line number Diff line change
Expand Up @@ -3436,6 +3436,14 @@
"start_hr" => "Time",
"end_hr" => "Time",
},
"v2.GetUsageMonthlyResources" => {
"filter_billing_dimension" => "String",
"filter_month" => "String",
"filter_view" => "MonthlyResourcesView",
"filter_include_descendants" => "Boolean",
"page_limit" => "Integer",
"page_next_record_id" => "String",
},
"v2.GetUsageObservabilityPipelines" => {
"start_hr" => "Time",
"end_hr" => "Time",
Expand Down
6 changes: 6 additions & 0 deletions features/v2/undo.json
Original file line number Diff line number Diff line change
Expand Up @@ -11713,6 +11713,12 @@
"type": "safe"
}
},
"GetUsageMonthlyResources": {
"tag": "Usage Metering",
"undo": {
"type": "safe"
}
},
"GetUsageObservabilityPipelines": {
"tag": "Usage Metering",
"undo": {
Expand Down
36 changes: 36 additions & 0 deletions features/v2/usage_metering.feature
Original file line number Diff line number Diff line change
Expand Up @@ -451,6 +451,42 @@ Feature: Usage Metering
And the response "data[0].type" is equal to "usage_timeseries"
And the response "data[0].attributes.product_family" is equal to "observability-pipelines"

@integration-only @team:ddoghq/billing-hub
Scenario: Get monthly usage by resource returns "Bad Request" response
Given new "GetUsageMonthlyResources" request
And request contains "filter[billing_dimension]" parameter with value "infra_host"
And request contains "filter[month]" parameter with value "not-a-month"
And request contains "filter[view]" parameter with value "all"
When the request is sent
Then the response status is 400 Bad Request
And the response "errors[0].status" is equal to "400"
And the response "errors[0].title" is equal to "Bad Request"
And the response "errors[0]" has field "detail"

@integration-only @team:ddoghq/billing-hub
Scenario: Get monthly usage by resource returns "OK" response
Given new "GetUsageMonthlyResources" request
And request contains "filter[billing_dimension]" parameter with value "infra_host"
And request contains "filter[month]" parameter with value "2026-04"
And request contains "filter[view]" parameter with value "all"
And request contains "page[limit]" parameter with value 1
When the request is sent
Then the response status is 200 OK
And the response "meta" has field "pagination"
And the response "meta.pagination" has field "next_record_id"

@integration-only @team:ddoghq/billing-hub
Scenario: Get monthly usage by resource supports non-host resources
Given new "GetUsageMonthlyResources" request
And request contains "filter[billing_dimension]" parameter with value "indexed_points"
And request contains "filter[month]" parameter with value "2026-04"
And request contains "filter[view]" parameter with value "all"
And request contains "page[limit]" parameter with value 1
When the request is sent
Then the response status is 200 OK
And the response "meta" has field "pagination"
And the response "meta.pagination" has field "next_record_id"

@generated @skip @team:ddoghq/billing-hub
Scenario: Get projected cost across your account returns "Bad Request" response
Given new "GetProjectedCost" request
Expand Down
7 changes: 7 additions & 0 deletions lib/datadog_api_client/inflector.rb
Original file line number Diff line number Diff line change
Expand Up @@ -6410,6 +6410,13 @@ def overrides
"v2.monthly_cost_attribution_meta" => "MonthlyCostAttributionMeta",
"v2.monthly_cost_attribution_pagination" => "MonthlyCostAttributionPagination",
"v2.monthly_cost_attribution_response" => "MonthlyCostAttributionResponse",
"v2.monthly_resource" => "MonthlyResource",
"v2.monthly_resource_attributes" => "MonthlyResourceAttributes",
"v2.monthly_resources_metadata" => "MonthlyResourcesMetadata",
"v2.monthly_resources_pagination" => "MonthlyResourcesPagination",
"v2.monthly_resources_response" => "MonthlyResourcesResponse",
"v2.monthly_resources_view" => "MonthlyResourcesView",
"v2.monthly_resource_type" => "MonthlyResourceType",
"v2.ms_teams_integration_metadata" => "MSTeamsIntegrationMetadata",
"v2.ms_teams_integration_metadata_teams_item" => "MSTeamsIntegrationMetadataTeamsItem",
"v2.mute_data_type" => "MuteDataType",
Expand Down
Loading
Loading