---
title: "Get all custom metrics by hourly average"
method: GET
path: "/api/v1/usage/top_avg_metrics"
tags: ["Usage Metering"]
---

# Get all custom metrics by hourly average

`GET /api/v1/usage/top_avg_metrics`

## Request

- Base URL: `https://api.datadoghq.com`
- URL: `https://api.datadoghq.com/api/v1/usage/top_avg_metrics`
- 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 all [custom metrics](https://docs.datadoghq.com/developers/metrics/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.

## Query parameters

- `month` string, date-time
- `day` string, date-time
- `names` string[]
- `limit` integer
- `next_record_id` string

## Response `200`

OK

- UsageTopAvgMetricsResponse: Response containing the number of hourly recorded custom metrics for a given organization.
  - `metadata` UsageTopAvgMetricsMetadata: The object containing document metadata.
    - `day` string, date-time: The day value from the user request that contains the returned usage data. (If day was used the request)
    - `month` string, date-time: The month value from the user request that contains the returned usage data. (If month was used the request)
    - `pagination` UsageTopAvgMetricsPagination: The metadata for the current pagination.
      - `limit` integer: Maximum amount of records to be returned.
      - `next_record_id` string, nullable: 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` integer, nullable: Total number of records.
  - `usage` UsageTopAvgMetricsHour[]: Number of hourly recorded custom metrics for a given organization.
    - `avg_metric_hour` integer: Average number of timeseries per hour in which the metric occurs.
    - `max_metric_hour` integer: Maximum number of timeseries per hour in which the metric occurs.
    - `metric_category` 'standard' | 'custom': Contains the metric category.
    - `metric_name` string: Contains the custom metric name.

## Other responses

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

---

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