---
title: Introduction to the Metric API
source: https://docs.newrelic.com/docs/data-apis/ingest-apis/metric-api/introduction-metric-api
---

New Relic's Metric API can be used to send [metric data](https://docs.newrelic.com/docs/using-new-relic/data/understand-data/new-relic-data-types#dimensional-metrics) to New Relic from a variety of sources. This API is how metrics from some of our integrations and exporters get into New Relic.

Want to try out our Metric API? [Create a New Relic account](https://newrelic.com/signup) for free! No credit card required.

## What is the Metric API? [#why-use]

The Metric API is a way to get metric data into New Relic. The API works by sending a POST request to our HTTP endpoint with a JSON payload containing the metric data.

The Metric API is how metrics are ingested from some of our [integrations](https://newrelic.com/instant-observability/), including our [open source exporters](https://docs.newrelic.com/docs/data-ingest-apis/get-data-new-relic/new-relic-sdks/telemetry-sdks-send-custom-telemetry-data-new-relic#external-data) (like DropWizard and Prometheus). The Metric API is also used by our [Telemetry SDKs](https://docs.newrelic.com/docs/data-ingest-apis/get-data-new-relic/new-relic-sdks/telemetry-sdks-send-custom-telemetry-data-new-relic), which are language-specific tools that make it easier to use our data-ingest APIs.

The Metric API can be used to:

-   Report metric data to New Relic without a New Relic agent.
-   Integrate metric data from an open source or in-house developed tool, library, or framework.
-   Fully control the metric data you're sending, including the resolution and associated dimensions.
-   Leverage the power of [NRQL](https://docs.newrelic.com/docs/query-data/nrql-new-relic-query-language/getting-started/introduction-nrql), New Relic's query language, for querying your [metric data](https://docs.newrelic.com/docs/using-new-relic/data/understand-data/new-relic-data-types#metrics).
-   Set up [alerts for your metric data](#create-alerts).

## Requirements

Ensure outbound connectivity on TCP port 443 is allowed to the [CIDR range](https://docs.newrelic.com/docs/using-new-relic/cross-product-functions/install-configure/networks/#infrastructure) that matches your [region](https://docs.newrelic.com/docs/using-new-relic/welcome-new-relic/get-started/our-eu-us-region-data-centers).
The preferred configuration method is to use the DNS name `metric-api.newrelic.com` (US, default), `metric-api.eu.newrelic.com` (EU), or `metric-api.jp.nr-data.net` (JP).

You'll need a New Relic license key for the New Relic account you want to send data to. For information on limits and restricted attributes, see [Metric API requirements and limits](https://docs.newrelic.com/docs/metric-api-general-requirements-limits).

## Get started

If we don't have an existing [integration or quickstart](https://newrelic.com/instant-observability/) that meets your metric-reporting needs, you have two options:

-   [Use our Telemetry SDKs](https://docs.newrelic.com/docs/data-ingest-apis/get-data-new-relic/new-relic-sdks/telemetry-sdks-send-custom-telemetry-data-new-relic), which are language-specific tools that help you send us metrics and other data.
-   [Use the Metric API directly](https://docs.newrelic.com/docs/report-metrics-metric-api).

## Find and use your data [#find-data]

You can find data sent via the Metric API (including from integrations that use this API) in these locations:

-   From **[one.newrelic.com](https://one.newrelic.com/all-capabilities)**, select **Explorer** and look for your service.
-   By querying the `Metric` data type. For example, you can use [NRQL](https://docs.newrelic.com/docs/query-data/nrql-new-relic-query-language/getting-started/introduction-nrql) to run:

    ```sql
    SELECT * FROM Metric
    ```

    For more on querying, see [Metric query examples](https://docs.newrelic.com/docs/data-ingest-apis/get-data-new-relic/metric-api/view-query-you-metric-data). For information on querying in general, see [Query data](https://docs.newrelic.com/docs/using-new-relic/data/understand-data/query-new-relic-data).

## Alert on metric data [#create-alerts]

To alert on metrics created with the Metric API, use [NRQL alert conditions](https://docs.newrelic.com/docs/alerts/new-relic-alerts/defining-conditions/create-alert-conditions-nrql-queries): Select the NRQL category when defining your condition, then use the `FROM Metric ...` NRQL query syntax to express it. When you create these alert conditions, alerts automatically uses the finest granularity data available (the raw metric data points) to evaluate alerts.

## Data retention [#retention]

All raw metric data points will be retained for 30 days. All additional aggregated data derived from the raw metric data points (for example, one-minute rollups) will be retained for 13 months. Any change to the retention period beyond such periods may result in a charge to you.

## Troubleshooting

See [Troubleshoot an `NrIntegrationError` event](https://docs.newrelic.com/docs/troubleshoot-nrintegrationerror-event).