--- title: Report metrics via the Metric API source: https://docs.newrelic.com/docs/data-apis/ingest-apis/metric-api/report-metrics-metric-api --- Use the [Metric API](https://docs.newrelic.com/docs/introduction-new-relic-metric-api) to send custom metrics to the New Relic platform. This document includes a quick start to send your first custom metric, plus detailed information on how to format and send your metric data. ## Quick start: Send metric data [#send-metric-data] We report the metric types `count`, `gauge`, and `summary`. For more information on metrics see [our documentation](https://docs.newrelic.com/docs/telemetry-data-platform/ingest-manage-data/understand-data/metric-data-type). Submit metric data to New Relic through an HTTP POST request. Compose each request with one or more metric data points, that consist of a `name`, a `timestamp`, and a `value` for the metric. Follow this example to send your first metric data points to New Relic: 1. Get the license key for the account you want to report data to. 2. Insert the license key into the following JSON, and then send the JSON to our [endpoint](#api-endpoint). 3. For `timestamp` replace `INSERT_CURRENT_TIMESTAMP` with a valid [epoch timestamp](#json-payload-keys). This example creates a single metric data point for a metric named `memory.heap`, but you can create additional attributes or data points by specifying [metric types](https://docs.newrelic.com/docs/telemetry-data-platform/ingest-manage-data/understand-data/metric-data-type) or adding [optional `common` blocks](#optional-map-attributes). ```bash curl -vvv -k -H "Content-Type: application/json" \ -H "Api-Key: NEW_RELIC_LICENSE_KEY" \ -X POST https://metric-api.newrelic.com/metric/v1 \ --data '[{ "metrics":[{ "name":"memory.heap", "type":"gauge", "value":2.3, "timestamp":INSERT_CURRENT_TIMESTAMP, "attributes":{"host.name":"dev.server.com"} }] }]' ``` The metric should be available in New Relic in a few seconds. You can query the data from any [NRQL interface](https://docs.newrelic.com/docs/query-data/nrql-new-relic-query-language/getting-started/introduction-nrql#where) using this query: ```sql FROM Metric SELECT max(memory.heap) TIMESERIES ``` For more on where data shows up, see [Find Metric API data](https://docs.newrelic.com/docs/data-ingest-apis/get-data-new-relic/metric-api/introduction-metric-api#find-data). ## Endpoint URL [#api-endpoint] Use an HTTP POST when sending metric data to the metric API endpoint: ``` https://metric-api.newrelic.com/metric/v1 ``` > #### 💡 TIP > > If your organization hosts data in the EU or JP data center, ensure you're using the correct regional endpoint. For this API: > > - EU endpoint: `https://metric-api.eu.newrelic.com/metric/v1` > - JP endpoint: `https://metric-api.jp.nr-data.net/metric/v1` ## HTTP request headers [#headers-query-parameters] Include the following HTTP request headers with the POST request. You can send some parameters as query parameters instead of request headers. | Header | Send as a query parameter? | Details | | ------------------ | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Content-Type` | No | **Required**. Must be `application/json`. | | `Content-Length` | No | **Required (usually set automatically by the HTTP client)**. The length of the request body in octets (8-bit bytes) unless sent with chunked encoding. This header is generally set by default by the underlying HTTP client sending the data and in most cases should not require any additional effort by the end user. | | `Api-Key` | Yes | **Required.** A license key for the account you want to report data to. If this is provided as both a header and a query parameter, the values must match. | | `Content-Encoding` | No | **Required if GZIP.** The value must be `GZIP` or `Identity.` If no value is present, then `Identity` is assumed. | | `x-request-id` | No | **Optional - Reserved for future use.** The value must be a valid `UUID4`. The value is expected to be unique for each request. | ## HTTP request body [#body-format] The body of the HTTP POST request must be in JSON format. The following describes the requirements and recommendations for the JSON payload. The payload must be encoded as **UTF-8**. ### Structure [#new-relic-guidelines] The JSON payload uses this structure: - The JSON payload is an array of maps. - Each map must contain a `metrics` key whose value is an array containing one or more metric data points. - A metric data point is identified by a `name`, `value`, and `timestamp` along with an optional set of attributes. **JSON payload creating two metrics** This example payload creates two metrics. `service.errors.all` is a count metric with three attributes and `service.memory` is a gauge metric with two attributes. ````json [ { "metrics": [ { "name": "service.errors.all", "type": "count", "value": 15, "timestamp":INSERT_CURRENT_TIMESTAMP, "interval.ms": 10000, "attributes": { "service.response.statuscode": "400", "host.name": "dev.server.com", "service.name": "foo" } }, { "name": "service.memory", "type": "gauge", "value": 2.7, "timestamp":INSERT_CURRENT_TIMESTAMP, "attributes": { "host.name": "dev.server.com", "app.name": "foo" } } ] } ] ``` ```` ### Required key-value pairs [#json-payload-keys] Each metric data point map in the `metrics` array uses the following key-value structure: | Key | Description | | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` _string_ | **Required**. The name of the metric. The value must be less than 255 characters. | | `value` _number_ or _map_ | **Required**. The value varies depending on the [metric type](https://docs.newrelic.com/docs/telemetry-data-platform/ingest-manage-data/understand-data/metric-data-type). For `gauge` and `count` the value should be a single number. For `summary`, the value should be a map with key-value pairs specifying the count, sum, min, and max. | | `timestamp` _long_ | **Required**. The metric's start time in [Unix time](https://currentmillis.com/). The default uses UTC time zone. This field also support seconds, microseconds, and nanoseconds. However, the data will be converted to milliseconds for storage and query. Metrics are dropped if they have a timestamp more than 48 hours in the past or more than 24 hours in the future from the time they are reported. | | `interval.ms` _positive long_ | **Required for `count` and `summary` [metric types](https://docs.newrelic.com/docs/telemetry-data-platform/ingest-manage-data/understand-data/metric-data-type)**. The length of the time window. | | `type` | Recommended. This should be one of the [supported metric types](https://docs.newrelic.com/docs/telemetry-data-platform/ingest-manage-data/understand-data/metric-data-type). If you do not specify a type, then this will default to a `gauge`. | | `attributes` _strings_, _JSON numbers_, or _booleans_ | Recommended. A map of key value pairs associated with this specific metric. Values can be strings, JSON numbers, or booleans. Keys are case-sensitive and must be less than 255 characters. | **JSON payload with three metric types** Here's an example payload containing one metric data point for each metric type: ````json [ { "metrics": [ { "name": "cache.misses", "type": "count", "value": 15, "timestamp":INSERT_CURRENT_TIMESTAMP, "interval.ms": 10000, "attributes": { "cache.name": "myCache", "host.name": "dev.server.com" } }, { "name": "temperature", "type": "gauge", "value": 15, "timestamp":INSERT_CURRENT_TIMESTAMP, "attributes": { "city": "Portland", "state": "Oregon" } }, { "name": "service.response.duration", "type": "summary", "value": { "count": 5, "sum": 0.004382655, "min": 0.0005093, "max": 0.001708826 }, "interval.ms": 10000, "timestamp":INSERT_CURRENT_TIMESTAMP, "attributes": { "host.name": "dev.server.com", "app.name": "foo" } } ] } ] ``` ```` ### Share attributes across metrics with `common` [#optional-map-attributes] If you want to include a set of attributes on multiple metrics (and not add the same attributes for each metric), you can use the `common` block. This is an optional map that specifies information that applies to all associated metric data points. Values in the common section will be overridden if the same key exists on a metric data point. The block can include: | Attribute | Description | | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `timestamp` _long_ | The metric's start time in [Unix time](https://currentmillis.com/). This defaults to the current time in the UTC time zone. This field also supports seconds, microseconds, and nanoseconds. However, the data will be converted to milliseconds for storage and later querying. | | `interval.ms` _positive long_ | **Required for `count` and `summary`.**The length of the time window. | | `attributes` _strings, JSON numbers, or booleans_ | A map of key-value pairs associated with this specific metric. Values can be strings, JSON numbers, or booleans. | **Example of `common` attributes** In the following example payload, three metrics are sent. All three metrics share `app.name` and `host.name` attributes, specified in the `common` block. Each metric also has a unique value for another attribute, `server.response.statuscode`. ````json [ { "common" : { "timestamp": 1531414060739, "interval.ms": 10000, "attributes": { "app.name": "foo", "host.name": "dev.server.com" } }, "metrics": [ { "name": "service.errors.all", "type": "count", "value": 9, "attributes": { "service.response.statuscode": "400" } }, { "name": "service.errors.all", "type": "count", "value": 4, "attributes": { "service.response.statuscode": "500" } }, { "name": "service.response.duration", "type": "summary", "value": { "count": 5, "sum": 0.004382655, "min": 0.0005093, "max": 0.001708826 }, "attributes": { "service.response.statuscode": "200" } } ] } ] ``` ```` ## Response validation and status codes [#response-validation] The Metric API returns a `202` response code for successful requests. When your data is accepted, an HTTP `202` response code is returned with a response structure like this: ``` HTTP/1.1 202 Accepted Content-Type: application/json; charset=UTF-8 Content-Length: 52 Access-Control-Allow-Methods: GET, POST, PUT, HEAD, OPTIONS Access-Control-Allow-Credentials: true Access-Control-Allow-Origin: * Connection: keep-alive {"requestId":"f0e7bfff-001a-b000-0000-01682bcf4565"} ``` ### Missing data with `202` response [#async-errors] A `202` code indicates the API did receive your data, and that the data passed basic validation checks. Normally, your data will be available for querying within a few seconds. However, New Relic runs additional validation asynchronously after receiving your data. If you receive a `202` response but can't find your metric, this indicates that New Relic found an error during this asynchronous validation. You can find these errors by querying [`NrIntegrationError` events](https://docs.newrelic.com/docs/telemetry-data-platform/manage-data/nrintegrationerror) in the account associated with the Insert API key you used. The `requestId` for each request will be tagged on the `NrIntegrationError` event. For more information, see [Troubleshoot an `NRIntegrationError` event](https://docs.newrelic.com/docs/troubleshoot-nrintegrationerror-event). ### Status codes [#response-status-codes] The Metric API can return the following HTTP status codes: | Status code | Definition | | ----------- | ----------------------------------------------------------------- | | `202` | Data accepted. | | `400` | Structure of the request is invalid. | | `403` | Authentication failure. | | `404` | The request path is incorrect. | | `405` | Used a request method other than POST. | | `408` | The request took too long to reach the endpoint. | | `411` | The `Content-Length` header wasn’t included. | | `413` | The payload was too big. Payloads must be under 1MB (10^6 bytes). | | `414` | The request URI was too long. | | `415` | The `Content-Type` or `Content-Encoding` was invalid. | | `429` | The request rate quota has been exceeded. | | `431` | The request headers are too long. | | `5xx` | There was a server error (please retry). |