• /
  • Log in
  • Free account

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.

Metric data is submitted to New Relic through an HTTP POST request. Each request is composed of one or more metric data points, which consist of a metric name, a timestamp, and a value.

Follow this example to send your first metric data points to New Relic:

  1. Find or register an Insert API key for your account: Go to: one.newrelic.com > account dropdown > Account settings > API keys, and select Insights API keys.

  2. Insert your API key into the following JSON, and then send the JSON to our endpoint.

    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.

    curl -vvv -k -H "Content-Type: application/json" \
    -H "Api-Key: YOUR_API_KEY_HERE" \
    -X POST https://metric-api.newrelic.com/metric/v1 \
    --data '[{ 
            "metrics":[{ 
               "name":"memory.heap", 
               "type":"gauge", 
               "value":2.3, 
               "timestamp":CURRENT_TIME_IN_MILLISECONDS_HERE, 
               "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 account hosts data in the EU data center, ensure you're using the proper API endpoints for EU region accounts.

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. The Insert API key authenticates you to use the Metric API. 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, type, and value along with an optional set of attributes.

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. Defaults to the current time in UTC timezone. This field also support seconds, microseconds, and nanoseconds. However, the data will be converted to milliseconds for storage and query. Metrics reported with a timestamp older than 48 hours ago or newer than 24 hours from the time they are reported are dropped.

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.

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

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 in the NrIntegrationError event in the account associated with the Insert API key you used. The requestId for each request will be tagged on the NrIntegrationError event. See Troubleshoot a NRIntegrationError event for more information.

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

For more help

If you need more help, check out these support and learning resources:

Create issueEdit page
Copyright © 2021 New Relic Inc.