The Metrics API in Datadog allows you to interact with and manage your metric data programmatically. With this API, you can submit custom metrics, retrieve metric data, manage tags associated with your metrics, and more. The API provides access to the full range of Datadog's metric-related features, making it a powerful tool for automating metric data management and integration.

You can submit custom metrics to Datadog through the Metrics API using the `POST` method. Custom metrics allow you to track data that is specific to your application or infrastructure.

- Endpoint: `https://api.datadoghq.com/api/v1/series`

- Request Method: `POST`

- Parameters:

1. `series`: A list of metrics to be submitted. Each metric consists of the following fields:
   1. `metric`: The name of the metric.
   2. `points`: A list of timestamp-value pairs, representing the metric data points.
   3. `tags`: A list of tags associated with the metric.
   4. `type`: The type of the metric (e.g., `gauge`, `count`, `rate`).
   5. `host`: The host associated with the metric.
   6. `device`: The device associated with the metric (optional).

- Example Request:

```json
{
    "series": [
        {
            "metric": "custom.metric",
            "points": [[<timestamp>, <value>]],
            "tags": ["env:prod", "app:web"],
            "type": "gauge",
            "host": "web-server-1"
        }
    ]
}
  Response: A successful request returns a 200 OK status with a response body indicating the success of the submission.

You can query your metrics to retrieve specific data points over time, perform aggregations, or analyze trends.

  Endpoint: https://api.datadoghq.com/api/v1/query

  Request Method: GET

  Parameters:
      start: The start of the time range (UNIX timestamp).
      end: The end of the time range (UNIX timestamp).
      query: The Datadog query string to filter and retrieve the metrics.

  Example Request:

  https://api.datadoghq.com/api/v1/query?start=1625112000&end=1625115600&query=avg:custom.metric{env:prod}

  Response: The API returns the metric data for the specified time range, including the metric values, timestamps, and any associated tags.

You can manage and view metadata for your metrics, including details such as the unit of measure, the metric type, and more.

  Endpoint: https://api.datadoghq.com/api/v1/metrics

  Request Method: GET

  Parameters:
      metric_name: The name of the metric for which metadata is being requested (optional).

  Example Request:

  https://api.datadoghq.com/api/v1/metrics?metric_name=custom.metric

  Response: The response includes metadata about the requested metric, including its type, tags, and other relevant details.

Metrics in Datadog can be tagged to provide better filtering and grouping for analysis. The Metrics API allows you to manage tags associated with your metrics.

  Endpoint: https://api.datadoghq.com/api/v1/tags/metrics

  Request Method: POST or DELETE

  Parameters:
      tags: The list of tags to be applied or removed from the metric.
      metric_name: The name of the metric to tag.

  Example Request:

  {
      "tags": ["env:prod", "region:us-west"],
      "metric_name": "custom.metric"
  }

  Response: A successful request returns a 200 OK status with a response body indicating the success of the tag modification.

The Metrics API allows you to fetch detailed information about the metric metadata, such as unit, description, and other configurations.

  Endpoint: https://api.datadoghq.com/api/v1/metrics/{metric_name}

  Request Method: GET

  Example Request:

  https://api.datadoghq.com/api/v1/metrics/custom.metric

  Response: The response will include the metadata associated with the metric, such as its description, tags, and other relevant details.

Datadog allows you to perform several types of aggregations to summarize metric data, including:

  Average: Computes the average value of the metric within the specified time range.
  Sum: Computes the total sum of the metric values.
  Max/Min: Computes the maximum or minimum values for the metric.
  Rate: Computes the rate of change of the metric.

These types of aggregations can be used in your metric queries to summarize and analyze large sets of data points.

  Example Query:

  avg:custom.metric{env:prod}.rollup(avg, 3600)

  This query will return the average of custom.metric aggregated over 1 hour.

While using the Metrics API, there are certain best practices and limitations to keep in mind:

  Rate limits: Datadog imposes rate limits on the Metrics API to prevent abuse and ensure performance. Be sure to review the API rate limits to avoid throttling.
  Data Granularity: Be mindful of the granularity of your metric data. High-resolution data can lead to large payloads and high ingestion costs.
  Tagging Strategy: Use consistent and well-planned tagging strategies to ensure that your metrics can be easily filtered and grouped for analysis.
  Time Series Data: Metric data is typically aggregated over time, so always ensure you are querying data with the appropriate time ranges for your use case.

The Datadog Metrics API provides powerful capabilities for programmatically interacting with your metrics, submitting custom metrics, querying metric data, managing metadata, and much more. Whether you are automating metric collection, analyzing performance, or integrating Datadog with other systems, the Metrics API is an essential tool for working with metrics in Datadog.

For more detailed documentation, visit the Datadog Metrics API Documentation.