---
title: "Get monthly usage by resource"
method: GET
path: "/api/v2/usage/monthly_resources"
tags: ["Usage Metering"]
---

# Get monthly usage by resource

`GET /api/v2/usage/monthly_resources`

## Request

- Base URL: `https://api.datadoghq.com`
- URL: `https://api.datadoghq.com/api/v2/usage/monthly_resources`
- Auth: one of:
  - API key in header `DD-API-KEY` and API key in header `DD-APPLICATION-KEY`
  - OAuth 2
    - Authorization code: `/oauth2/v1/authorize`
    - Token URL: `/oauth2/v1/token` scopes: `usage_read`

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.

## Query parameters

- `filter[billing_dimension]` string, required
- `filter[month]` string, required
- `filter[view]` 'billable' | 'all', required: Whether to return billable resources or the full monthly resource breakdown.
- `filter[include_descendants]` boolean
- `page[limit]` integer
- `page[next_record_id]` string

## Response `200`

OK

- MonthlyResourcesResponse: Monthly usage for host and non-host resources.
  - `data` MonthlyResource[]: Resource usage records. Empty when no matching resources are available.
    - `attributes` MonthlyResourceAttributes: Resource usage and organization details for the requested month.
      - `data_date` string: Date of the source usage data. May be empty when unavailable.
      - `org_name` string: Name of the organization that owns the resource.
      - `public_id` string: Public ID of the organization that owns the resource.
      - `resource_name` string: Name of the resource, such as a host name, metric name, or log index.
      - `tags` object: Resource tags when available. Empty for resource types without tag data.
      - `timestamp` string: Selected billing hour for percentile usage, or the first day of the month for monthly usage. May be empty when unavailable.
      - `usage_type` string: Usage type of the resource. Values depend on the billing dimension and are not limited to host types.
      - `usage_value` number, double, nullable: Usage attributed to the resource in the units of the requested billing dimension. Values can be fractional.
    - `id` string: Identifier for the resource usage record. Treat this value as opaque.
    - `type` 'monthly_resource': Type of a monthly resource usage record.
  - `meta` MonthlyResourcesMetadata: Metadata for monthly resource usage.
    - `pagination` MonthlyResourcesPagination: Pagination information for monthly resource usage.
      - `next_record_id` string, nullable: Cursor for the next request. Pass as `page[next_record_id]` with the same filters. Null when there are no more results.

## Other responses

- `400`: Bad Request
- `403`: Forbidden - User is not authorized
- `429`: Too many requests

## Changes

- **2026-11-17** `0e6a76c41b97`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/changes/api/v2/usage/monthly_resources/get.md)

---

[API](https://skmtc.dev/datadog/apis/datadog-api-v2-collection.md) - [All operations](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/llms.txt) - [OpenAPI document](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/revisions/8d1a5e5973da?raw)
