Usage Metering

Get monthly usage by resource

Changed on

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.

get/api/v2/usage/monthly_resources

Request

  • Base URL
    https://api.datadoghq.com
  • Auth
    • API key in header DD-API-KEY and API key in header DD-APPLICATION-KEY
    • or OAuth 2
      Authorization code/oauth2/v1/authorize
      Token URL/oauth2/v1/token
      Scopesusage_read

Query parameters

filter[billing_dimension]string required

Billing dimension to retrieve, such as infra_host, indexed_points, or logs_indexed_30day.

filter[month]string required

Month of usage to retrieve in YYYY-MM format.

filter[view]'billable' | 'all' required

Whether to return billable resources or the full monthly resource breakdown.

Set to billable to return resources that contribute to billable usage, or all to return the full monthly resource breakdown.

filter[include_descendants]boolean

Include usage for descendant organizations of the authenticated organization.

page[limit]integer

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.

page[next_record_id]string

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.

Response

OK

Changes