---
title: Get monthly usage by resource
description: Get resource-level usage for a billing dimension and month, using the same data as the resource breakdown in Plan & Usage.
breadcrumbs: Docs > API > Get monthly usage by resource
---

> For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt).

# Get monthly usage by resource

## v2 (latest)

| Datadog site      | API endpoint                                                     |
| ----------------- | ---------------------------------------------------------------- |
| app.datadoghq.com | GET https://api.datadoghq.com/api/v2/usage/monthly_resources     |
| us3.datadoghq.com | GET https://api.us3.datadoghq.com/api/v2/usage/monthly_resources |
| us5.datadoghq.com | GET https://api.us5.datadoghq.com/api/v2/usage/monthly_resources |
| app.datadoghq.eu  | GET https://api.datadoghq.eu/api/v2/usage/monthly_resources      |
| ap1.datadoghq.com | GET https://api.ap1.datadoghq.com/api/v2/usage/monthly_resources |
| ap2.datadoghq.com | GET https://api.ap2.datadoghq.com/api/v2/usage/monthly_resources |
| uk1.datadoghq.com | GET https://api.uk1.datadoghq.com/api/v2/usage/monthly_resources |
| app.ddog-gov.com  | GET https://api.ddog-gov.com/api/v2/usage/monthly_resources      |
| us2.ddog-gov.com  | GET https://api.us2.ddog-gov.com/api/v2/usage/monthly_resources  |

### Overview

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.

This endpoint requires the `usage_read` permission.

OAuth apps require the `usage_read` authorization [scope](https://docs.datadoghq.com/api/latest/scopes.md#usage-metering) to access this endpoint.

### Arguments

#### Query Strings

| Field                                  | Type    | Description                                                                                                                                                                                                                                                         |
| -------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filter[billing_dimension] [*required*] | string  | Billing dimension to retrieve, such as `infra_host`, `indexed_points`, or `logs_indexed_30day`.                                                                                                                                                                     |
| filter[month] [*required*]             | string  | Month of usage to retrieve in `YYYY-MM` format.                                                                                                                                                                                                                     |
| filter[view] [*required*]              | enum    | Set to `billable` to return resources that contribute to billable usage, or `all` to return the full monthly resource breakdown. Allowed enum values: `billable`, `all`.                                                                                            |
| filter[include_descendants]            | boolean | Include usage for descendant organizations of the authenticated organization. Default: `false`.                                                                                                                                                                     |
| 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. Default: `100000`. |
| 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

{% tabs %}
{% tab label="200" %}
OK

{% tabs %}
{% tab label="Model" %}
Monthly usage for host and non-host resources.

| Parent field         | Field          | Type     | Description                                                                                                                 |
| -------------------- | -------------- | -------- | --------------------------------------------------------------------------------------------------------------------------- |
|                      | data           | [object] | Resource usage records. Empty when no matching resources are available.                                                     |
| data                 | attributes     | object   | Resource usage and organization details for the requested month.                                                            |
| attributes           | data_date      | string   | Date of the source usage data. May be empty when unavailable.                                                               |
| attributes           | org_name       | string   | Name of the organization that owns the resource.                                                                            |
| attributes           | public_id      | string   | Public ID of the organization that owns the resource.                                                                       |
| attributes           | resource_name  | string   | Name of the resource, such as a host name, metric name, or log index.                                                       |
| attributes           | tags           | object   | Resource tags when available. Empty for resource types without tag data.                                                    |
| additionalProperties | <any-key>      | string   |                                                                                                                             |
| attributes           | timestamp      | string   | Selected billing hour for percentile usage, or the first day of the month for monthly usage. May be empty when unavailable. |
| attributes           | usage_type     | string   | Usage type of the resource. Values depend on the billing dimension and are not limited to host types.                       |
| attributes           | usage_value    | double   | Usage attributed to the resource in the units of the requested billing dimension. Values can be fractional.                 |
| data                 | id             | string   | Identifier for the resource usage record. Treat this value as opaque.                                                       |
| data                 | type           | enum     | Type of a monthly resource usage record. Allowed enum values: `monthly_resource`. Default: `monthly_resource`.              |
|                      | meta           | object   | Metadata for monthly resource usage.                                                                                        |
| meta                 | pagination     | object   | Pagination information for monthly resource usage.                                                                          |
| pagination           | next_record_id | string   | Cursor for the next request. Pass as `page[next_record_id]` with the same filters. Null when there are no more results.     |
{% /tab %}

{% tab label="Example" %}
```json
{
  "data": [
    {
      "attributes": {
        "data_date": "string",
        "org_name": "string",
        "public_id": "string",
        "resource_name": "string",
        "tags": {
          "<any-key>": "string"
        },
        "timestamp": "string",
        "usage_type": "string",
        "usage_value": "number"
      },
      "id": "string",
      "type": "string"
    }
  ],
  "meta": {
    "pagination": {
      "next_record_id": "string"
    }
  }
}
```
{% /tab %}
{% /tabs %}
{% /tab %}

{% tab label="400" %}
Bad Request

{% tabs %}
{% tab label="Model" %}
API error response.

| Parent field | Field               | Type     | Description                                                                     |
| ------------ | ------------------- | -------- | ------------------------------------------------------------------------------- |
|              | errors [*required*] | [object] | A list of errors.                                                               |
| errors       | code                | string   | An application-specific error code.                                             |
| errors       | detail              | string   | A human-readable explanation specific to this occurrence of the error.          |
| errors       | meta                | object   | Non-standard meta-information about the error                                   |
| errors       | source              | object   | References to the source of the error.                                          |
| source       | header              | string   | A string indicating the name of a single request header which caused the error. |
| source       | parameter           | string   | A string indicating which URI query parameter caused the error.                 |
| source       | pointer             | string   | A JSON pointer to the value in the request document that caused the error.      |
| errors       | status              | string   | Status code of the response.                                                    |
| errors       | title               | string   | Short human-readable summary of the error.                                      |
{% /tab %}

{% tab label="Example" %}
```json
{
  "errors": [
    {
      "code": "invalid_request",
      "detail": "Missing required attribute in body",
      "meta": {},
      "source": {
        "header": "Authorization",
        "parameter": "limit",
        "pointer": "/data/attributes/title"
      },
      "status": "400",
      "title": "Bad Request"
    }
  ]
}
```
{% /tab %}
{% /tabs %}
{% /tab %}

{% tab label="403" %}
Forbidden - User is not authorized

{% tabs %}
{% tab label="Model" %}
API error response.

| Parent field | Field               | Type     | Description                                                                     |
| ------------ | ------------------- | -------- | ------------------------------------------------------------------------------- |
|              | errors [*required*] | [object] | A list of errors.                                                               |
| errors       | code                | string   | An application-specific error code.                                             |
| errors       | detail              | string   | A human-readable explanation specific to this occurrence of the error.          |
| errors       | meta                | object   | Non-standard meta-information about the error                                   |
| errors       | source              | object   | References to the source of the error.                                          |
| source       | header              | string   | A string indicating the name of a single request header which caused the error. |
| source       | parameter           | string   | A string indicating which URI query parameter caused the error.                 |
| source       | pointer             | string   | A JSON pointer to the value in the request document that caused the error.      |
| errors       | status              | string   | Status code of the response.                                                    |
| errors       | title               | string   | Short human-readable summary of the error.                                      |
{% /tab %}

{% tab label="Example" %}
```json
{
  "errors": [
    {
      "code": "invalid_request",
      "detail": "Missing required attribute in body",
      "meta": {},
      "source": {
        "header": "Authorization",
        "parameter": "limit",
        "pointer": "/data/attributes/title"
      },
      "status": "400",
      "title": "Bad Request"
    }
  ]
}
```
{% /tab %}
{% /tabs %}
{% /tab %}

{% tab label="429" %}
Too many requests

{% tabs %}
{% tab label="Model" %}
API error response.

| Field               | Type     | Description       |
| ------------------- | -------- | ----------------- |
| errors [*required*] | [string] | A list of errors. |
{% /tab %}

{% tab label="Example" %}
```json
{
  "errors": [
    "Bad Request"
  ]
}
```
{% /tab %}
{% /tabs %}
{% /tab %}
{% /tabs %}

### Code Example

{% tabs %}
{% tab label="Curl" %}
```bash
# Required query arguments
export filter_billing_dimension="infra_host"
export filter_month="2026-04"
export filter_view="billable"

# Set your Datadog site and credentials
export DD_SITE="datadoghq.com" # Or us3.datadoghq.com, us5.datadoghq.com, datadoghq.eu, ap1.datadoghq.com, ap2.datadoghq.com, uk1.datadoghq.com, ddog-gov.com, us2.ddog-gov.com
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X GET "https://api.${DD_SITE}/api/v2/usage/monthly_resources?filter%5Bbilling_dimension%5D=${filter_billing_dimension}&filter%5Bmonth%5D=${filter_month}&filter%5Bview%5D=${filter_view}" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}"
```
{% /tab %}
{% /tabs %}
