Get all custom metrics by hourly average

GET https://api.ap1.datadoghq.com/api/v1/usage/top_avg_metricshttps://api.ap2.datadoghq.com/api/v1/usage/top_avg_metricshttps://api.datadoghq.eu/api/v1/usage/top_avg_metricshttps://api.ddog-gov.com/api/v1/usage/top_avg_metricshttps://api.us2.ddog-gov.com/api/v1/usage/top_avg_metricshttps://api.datadoghq.com/api/v1/usage/top_avg_metricshttps://api.us3.datadoghq.com/api/v1/usage/top_avg_metricshttps://api.us5.datadoghq.com/api/v1/usage/top_avg_metrics

Overview

Get all custom metrics by hourly average. Use the month parameter to get a month-to-date data resolution or use the day parameter to get a daily resolution. One of the two is required, and only one of the two is allowed. 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

month

string

Datetime in ISO-8601 format, UTC, precise to month: [YYYY-MM] for usage beginning at this hour. (Either month or day should be specified, but not both)

day

string

Datetime in ISO-8601 format, UTC, precise to day: [YYYY-MM-DD] for usage beginning at this hour. (Either month or day should be specified, but not both)

names

array

Comma-separated list of metric names.

limit

integer

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

next_record_id

string

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

Response

OK

Response containing the number of hourly recorded custom metrics for a given organization.

Expand All

Field

Type

Description

metadata

object

The object containing document metadata.

day

date-time

The day value from the user request that contains the returned usage data. (If day was used the request)

month

date-time

The month value from the user request that contains the returned usage data. (If month was used the request)

pagination

object

The metadata for the current pagination.

limit

int64

Maximum amount of records to be returned.

next_record_id

string

The cursor to get the next results (if any). To make the next request, use the same parameters and add next_record_id.

total_number_of_records

int64

Total number of records.

usage

[object]

Number of hourly recorded custom metrics for a given organization.

avg_metric_hour

int64

Average number of timeseries per hour in which the metric occurs.

max_metric_hour

int64

Maximum number of timeseries per hour in which the metric occurs.

metric_category

enum

Contains the metric category. Allowed enum values: standard,custom

metric_name

string

Contains the custom metric name.

{
  "metadata": {
    "day": "2019-09-19T10:00:00.000Z",
    "month": "2019-09-19T10:00:00.000Z",
    "pagination": {
      "limit": "integer",
      "next_record_id": "string",
      "total_number_of_records": "integer"
    }
  },
  "usage": [
    {
      "avg_metric_hour": "integer",
      "max_metric_hour": "integer",
      "metric_category": "string",
      "metric_name": "string"
    }
  ]
}

Bad Request

Error response object.

Expand All

Field

Type

Description

errors [required]

[string]

Array of errors returned by the API.

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

Forbidden - User is not authorized

Error response object.

Expand All

Field

Type

Description

errors [required]

[string]

Array of errors returned by the API.

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

Too many requests

Error response object.

Expand All

Field

Type

Description

errors [required]

[string]

Array of errors returned by the API.

{
  "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.us2.ddog-gov.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v1/usage/top_avg_metrics" \ -H "Accept: application/json" \ -H "DD-API-KEY: ${DD_API_KEY}" \ -H "DD-APPLICATION-KEY: ${DD_APP_KEY}"
"""
Get all custom metrics by hourly average returns "OK" response
"""

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

configuration = Configuration()
with ApiClient(configuration) as api_client:
    api_instance = UsageMeteringApi(api_client)
    response = api_instance.get_usage_top_avg_metrics(
        day=(datetime.now() + relativedelta(days=-3)),
    )

    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.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" python3 "example.py"
# Get all custom metrics by hourly average returns "OK" response

require "datadog_api_client"
api_instance = DatadogAPIClient::V1::UsageMeteringAPI.new
opts = {
  day: (Time.now + -3 * 86400),
}
p api_instance.get_usage_top_avg_metrics(opts)

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.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" rb "example.rb"
// Get all custom metrics by hourly average returns "OK" response

package main

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

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

func main() {
	ctx := datadog.NewDefaultContext(context.Background())
	configuration := datadog.NewConfiguration()
	apiClient := datadog.NewAPIClient(configuration)
	api := datadogV1.NewUsageMeteringApi(apiClient)
	resp, r, err := api.GetUsageTopAvgMetrics(ctx, *datadogV1.NewGetUsageTopAvgMetricsOptionalParameters().WithDay(time.Now().AddDate(0, 0, -3)))

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

	responseContent, _ := json.MarshalIndent(resp, "", "  ")
	fmt.Fprintf(os.Stdout, "Response from `UsageMeteringApi.GetUsageTopAvgMetrics`:\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.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" go run "main.go"
// Get all custom metrics by hourly average returns "OK" response
import com.datadog.api.client.ApiClient;
import com.datadog.api.client.ApiException;
import com.datadog.api.client.v1.api.UsageMeteringApi;
import com.datadog.api.client.v1.api.UsageMeteringApi.GetUsageTopAvgMetricsOptionalParameters;
import com.datadog.api.client.v1.model.UsageTopAvgMetricsResponse;
import java.time.OffsetDateTime;

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

    try {
      UsageTopAvgMetricsResponse result =
          apiInstance.getUsageTopAvgMetrics(
              new GetUsageTopAvgMetricsOptionalParameters().day(OffsetDateTime.now().plusDays(-3)));
      System.out.println(result);
    } catch (ApiException e) {
      System.err.println("Exception when calling UsageMeteringApi#getUsageTopAvgMetrics");
      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.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" java "Example.java"
// Get all custom metrics by hourly average returns "OK" response
use chrono::{DateTime, Utc};
use datadog_api_client::datadog;
use datadog_api_client::datadogV1::api_usage_metering::GetUsageTopAvgMetricsOptionalParams;
use datadog_api_client::datadogV1::api_usage_metering::UsageMeteringAPI;

#[tokio::main]
async fn main() {
    let configuration = datadog::Configuration::new();
    let api = UsageMeteringAPI::with_config(configuration);
    let resp = api
        .get_usage_top_avg_metrics(
            GetUsageTopAvgMetricsOptionalParams::default().day(
                DateTime::parse_from_rfc3339("2021-11-08T11:11:11+00:00")
                    .expect("Failed to parse datetime")
                    .with_timezone(&Utc),
            ),
        )
        .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.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" cargo run
/**
 * Get all custom metrics by hourly average returns "OK" response
 */

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

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

const params: v1.UsageMeteringApiGetUsageTopAvgMetricsRequest = {
  day: new Date(new Date().getTime() + -3 * 86400 * 1000),
};

apiInstance
  .getUsageTopAvgMetrics(params)
  .then((data: v1.UsageTopAvgMetricsResponse) => {
    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.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" tsc "example.ts"