Usage Metering

The usage metering API allows you to get hourly, daily, and monthly usage across multiple facets of Datadog. This API is available to all Pro and Enterprise customers.

Note: Usage data is delayed by up to 72 hours from when it was incurred. It is retained for 15 months.

You can retrieve up to 24 hours of hourly usage data for multiple organizations, and up to two months of hourly usage data for a single organization in one request. Learn more on the usage details documentation.

Get billing dimension mapping for usage endpoints

v2 (latest)

GET https://api.ap1.datadoghq.com/api/v2/usage/billing_dimension_mappinghttps://api.ap2.datadoghq.com/api/v2/usage/billing_dimension_mappinghttps://api.datadoghq.eu/api/v2/usage/billing_dimension_mappinghttps://api.ddog-gov.com/api/v2/usage/billing_dimension_mappinghttps://api.datadoghq.com/api/v2/usage/billing_dimension_mappinghttps://api.us3.datadoghq.com/api/v2/usage/billing_dimension_mappinghttps://api.us5.datadoghq.com/api/v2/usage/billing_dimension_mapping

Overview

Get a mapping of billing dimensions to the corresponding keys for the supported usage metering public API endpoints. Mapping data is updated on a monthly cadence.

This endpoint is only accessible to parent-level organizations.

This endpoint requires the usage_read permission.

OAuth apps require the usage_read authorization scope to access this endpoint.

Arguments

Query Strings

Name

Type

Description

filter[month]

string

Datetime in ISO-8601 format, UTC, and for mappings beginning this month. Defaults to the current month.

filter[view]

string

String to specify whether to retrieve active billing dimension mappings for the contract or for all available mappings. Allowed views have the string active or all. Defaults to active.

Response

Billing dimensions mapping response.

Expand All

Field

Type

Description

data

[object]

Billing dimensions mapping data.

{
  "data": [
    {
      "attributes": {
        "endpoints": [
          {
            "id": "api/v1/usage/billable-summary",
            "keys": [
              "apm_host_top99p",
              "apm_host_sum"
            ],
            "status": "string"
          }
        ],
        "in_app_label": "APM Hosts",
        "timestamp": "2019-09-19T10:00:00.000Z"
      },
      "id": "string",
      "type": "string"
    }
  ]
}

Bad Request

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Forbidden - User is not authorized

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Too many requests

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Code Example

                  # Curl command
curl -X GET "https://api.ap1.datadoghq.com"https://api.ap2.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/usage/billing_dimension_mapping" \
-H "Accept: application/json" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}"

                

"""
Get billing dimension mapping for usage endpoints returns "OK" response
"""

from datadog_api_client import ApiClient, Configuration
from datadog_api_client.v2.api.usage_metering_api import UsageMeteringApi

configuration = Configuration()
with ApiClient(configuration) as api_client:
    api_instance = UsageMeteringApi(api_client)
    response = api_instance.get_billing_dimension_mapping()

    print(response)

Instructions

First install the library and its dependencies and then save the example to example.py and run following commands:

    DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" python3 "example.py"

# Get billing dimension mapping for usage endpoints returns "OK" response

require "datadog_api_client"
api_instance = DatadogAPIClient::V2::UsageMeteringAPI.new
p api_instance.get_billing_dimension_mapping()

Instructions

First install the library and its dependencies and then save the example to example.rb and run following commands:

    DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" rb "example.rb"

// Get billing dimension mapping for usage endpoints returns "OK" response

package main

import (
	"context"
	"encoding/json"
	"fmt"
	"os"

	"github.com/DataDog/datadog-api-client-go/v2/api/datadog"
	"github.com/DataDog/datadog-api-client-go/v2/api/datadogV2"
)

func main() {
	ctx := datadog.NewDefaultContext(context.Background())
	configuration := datadog.NewConfiguration()
	apiClient := datadog.NewAPIClient(configuration)
	api := datadogV2.NewUsageMeteringApi(apiClient)
	resp, r, err := api.GetBillingDimensionMapping(ctx, *datadogV2.NewGetBillingDimensionMappingOptionalParameters())

	if err != nil {
		fmt.Fprintf(os.Stderr, "Error when calling `UsageMeteringApi.GetBillingDimensionMapping`: %v\n", err)
		fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
	}

	responseContent, _ := json.MarshalIndent(resp, "", "  ")
	fmt.Fprintf(os.Stdout, "Response from `UsageMeteringApi.GetBillingDimensionMapping`:\n%s\n", responseContent)
}

Instructions

First install the library and its dependencies and then save the example to main.go and run following commands:

    DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" go run "main.go"

// Get billing dimension mapping for usage endpoints 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.model.BillingDimensionsMappingResponse;

public class Example {
  public static void main(String[] args) {
    ApiClient defaultClient = ApiClient.getDefaultApiClient();
    UsageMeteringApi apiInstance = new UsageMeteringApi(defaultClient);

    try {
      BillingDimensionsMappingResponse result = apiInstance.getBillingDimensionMapping();
      System.out.println(result);
    } catch (ApiException e) {
      System.err.println("Exception when calling UsageMeteringApi#getBillingDimensionMapping");
      System.err.println("Status code: " + e.getCode());
      System.err.println("Reason: " + e.getResponseBody());
      System.err.println("Response headers: " + e.getResponseHeaders());
      e.printStackTrace();
    }
  }
}

Instructions

First install the library and its dependencies and then save the example to Example.java and run following commands:

    DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" java "Example.java"

// Get billing dimension mapping for usage endpoints returns "OK" response
use datadog_api_client::datadog;
use datadog_api_client::datadogV2::api_usage_metering::GetBillingDimensionMappingOptionalParams;
use datadog_api_client::datadogV2::api_usage_metering::UsageMeteringAPI;

#[tokio::main]
async fn main() {
    let configuration = datadog::Configuration::new();
    let api = UsageMeteringAPI::with_config(configuration);
    let resp = api
        .get_billing_dimension_mapping(GetBillingDimensionMappingOptionalParams::default())
        .await;
    if let Ok(value) = resp {
        println!("{:#?}", value);
    } else {
        println!("{:#?}", resp.unwrap_err());
    }
}

Instructions

First install the library and its dependencies and then save the example to src/main.rs and run following commands:

    DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" cargo run

/**
 * Get billing dimension mapping for usage endpoints returns "OK" response
 */

import { client, v2 } from "@datadog/datadog-api-client";

const configuration = client.createConfiguration();
const apiInstance = new v2.UsageMeteringApi(configuration);

apiInstance
  .getBillingDimensionMapping()
  .then((data: v2.BillingDimensionsMappingResponse) => {
    console.log(
      "API called successfully. Returned data: " + JSON.stringify(data)
    );
  })
  .catch((error: any) => console.error(error));

Instructions

First install the library and its dependencies and then save the example to example.ts and run following commands:

    DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" tsc "example.ts"

Get hourly usage by product family

v2 (latest)

GET https://api.ap1.datadoghq.com/api/v2/usage/hourly_usagehttps://api.ap2.datadoghq.com/api/v2/usage/hourly_usagehttps://api.datadoghq.eu/api/v2/usage/hourly_usagehttps://api.ddog-gov.com/api/v2/usage/hourly_usagehttps://api.datadoghq.com/api/v2/usage/hourly_usagehttps://api.us3.datadoghq.com/api/v2/usage/hourly_usagehttps://api.us5.datadoghq.com/api/v2/usage/hourly_usage

Overview

Get hourly usage by product family. This endpoint requires the usage_read permission.

OAuth apps require the usage_read authorization scope to access this endpoint.

Arguments

Query Strings

Name

Type

Description

filter[timestamp][start] [required]

string

Datetime in ISO-8601 format, UTC, precise to hour: [YYYY-MM-DDThh] for usage beginning at this hour.

filter[timestamp][end]

string

Datetime in ISO-8601 format, UTC, precise to hour: [YYYY-MM-DDThh] for usage ending before this hour.

filter[product_families] [required]

string

Comma separated list of product families to retrieve. Available families are all, analyzed_logs, application_security, audit_trail, serverless, ci_app, cloud_cost_management, cloud_siem, csm_container_enterprise, csm_host_enterprise, cspm, custom_events, cws, dbm, error_tracking, fargate, infra_hosts, incident_management, indexed_logs, indexed_spans, ingested_spans, iot, lambda_traced_invocations, llm_observability, logs, network_flows, network_hosts, network_monitoring, observability_pipelines, online_archive, profiling, product_analytics, rum, rum_browser_sessions, rum_mobile_sessions, sds, snmp, software_delivery, synthetics_api, synthetics_browser, synthetics_mobile, synthetics_parallel_testing, timeseries, vuln_management and workflow_executions. The following product family has been deprecated: audit_logs.

filter[include_descendants]

boolean

Include child org usage in the response. Defaults to false.

filter[include_connected_accounts]

boolean

Boolean to specify whether to include accounts connected to the current account as partner customers in the Datadog partner network program. Defaults to false.

filter[include_breakdown]

boolean

Include breakdown of usage by subcategories where applicable (for product family logs only). Defaults to false.

filter[versions]

string

Comma separated list of product family versions to use in the format product_family:version. For example, infra_hosts:1.0.0. If this parameter is not used, the API will use the latest version of each requested product family. Currently all families have one version 1.0.0.

page[limit]

integer

Maximum number of results to return (between 1 and 500) - defaults to 500 if limit not specified.

page[next_record_id]

string

List following results with a next_record_id provided in the previous query.

Response

Hourly usage response.

Expand All

Field

Type

Description

data

[object]

Response containing hourly usage.

Code Example

                  # Required query arguments
export filter[timestamp][start]="CHANGE_ME"
export filter[product_families]="CHANGE_ME"
# Curl command
curl -X GET "https://api.ap1.datadoghq.com"https://api.ap2.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/usage/hourly_usage?filter[timestamp][start]=${filter[timestamp][start]}&filter[product_families]=${filter[product_families]}" \
-H "Accept: application/json" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}"

                

"""
Get hourly usage by product family returns "OK" response
"""

from datetime import datetime
from dateutil.relativedelta import relativedelta
from datadog_api_client import ApiClient, Configuration
from datadog_api_client.v2.api.usage_metering_api import UsageMeteringApi

configuration = Configuration()
with ApiClient(configuration) as api_client:
    api_instance = UsageMeteringApi(api_client)
    response = api_instance.get_hourly_usage(
        filter_timestamp_start=(datetime.now() + relativedelta(days=-3)),
        filter_product_families="infra_hosts",
    )

    print(response)

Instructions

First install the library and its dependencies and then save the example to example.py and run following commands:

    DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" python3 "example.py"

# Get hourly usage by product family returns "OK" response

require "datadog_api_client"
api_instance = DatadogAPIClient::V2::UsageMeteringAPI.new
p api_instance.get_hourly_usage((Time.now + -3 * 86400), "infra_hosts")

Instructions

First