Report metrics via the Metric API

Use the 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

We report the metric types count, gauge, and summary. For more information on metrics see our documentation.

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:

Get the for the account you want to report data to.
Insert the license key into the following JSON, and then send the JSON to our endpoint.
For timestamp replace INSERT_CURRENT_TIMESTAMP with a valid epoch timestamp. 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 or adding optional common blocks.
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 using this query:

FROM Metric SELECT max(memory.heap) TIMESERIES

For more on where data shows up, see Find Metric API data.

Endpoint URL

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 data center, ensure you're using the EU region endpoints. For this API, the EU endpoint is:

https://metric-api.eu.newrelic.com/metric/v1

HTTP request headers

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 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

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

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.

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.

[
  {
    "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

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. 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. 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. The length of the time window.
`type`	Recommended. This should be one of the supported metric types. 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.

Here's an example payload containing one metric data point for each metric type:

[
  {
    "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`

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. 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.

Attribute

Description

timestamp

long

The metric's start time in Unix time. 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.

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.

[
  {
    "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

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

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 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.

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).

Quick start: Send metric data

Endpoint URL

Tip

HTTP request headers

HTTP request body

Structure

JSON payload creating two metrics

Required key-value pairs

JSON payload with three metric types

Share attributes across metrics with `common`

Example of `common` attributes

Response validation and status codes

Missing data with `202` response

Status codes

Report metrics via the Metric API

Quick start: Send metric data .css-21sua1{background:none;border:none;width:0;padding:0;}

Endpoint URL

Tip

HTTP request headers

HTTP request body

Structure

Required key-value pairs

JSON payload with three metric types

Share attributes across metrics with common

Example of common attributes

Response validation and status codes

Missing data with 202 response

Status codes

Quick start: Send metric data

Share attributes across metrics with `common`

Example of `common` attributes

Missing data with `202` response