Metric API limits and restricted attributes

This document describes data requirements for the Metric API, including:

  • Data specifications and max limits
  • Restricted attributes

For instructions on sending metric data and formatting of the JSON payload, see Report metrics via the Metric API.

The metric API is in a limited free period. For information about limits during the free period, see Introduction to the Metric API.

Endpoint requirements and maximum limits

All metric data is sent via a POST to:

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

If your account hosts data in the EU data center, ensure you're using the proper API endpoints for EU region accounts.

The following default limits apply for all metric data:

Condition Limit
Max data points per minute (DPM)* 100k
Max unique timeseries per account per day* 50k (A timeseries is a single, unique combination of a metric name and any attributes.)
Max payloads per minute 10k
Max attributes per metric 50
Max metric attribute name length 255 characters
Max characters for an attribute key 255 characters
Max metric attribute value length 4096 characters
Allowed HTTP protocols HTTPS only
Numerical long values falling outside minimum or maximum Java long values Numerical long values that fall outside of the minimum or maximum Java long value will be rejected. If the number is in the common block, then the entire block will be dropped. If the number is in a metric data point, then the metric data point it resides in will be dropped.
Numerical double values falling outside minimum or maximum Java double values Numeric double values that fall outside of a the minimum or maximum Java double value will be rejected. If the number is in the common block, then the entire block will be dropped. If the number is in a metric data point, then the metric data point it resides in will be dropped.
Payload size Total maximum size or length: 1 MB maximum per POST. We highly recommend using compression.
Attribute naming syntax Attribute names can be a combination of alphanumeric characters, colons (:), periods (.), and underscores (_).

*Metric API limits apply at the individual account level. To inquire about raising your metric rate limits, contact your New Relic sales representative or e-mail rate-limit-request@newrelic.com with your account id(s) and requested limits.

Rate limit violations

This section describes how the Metric API behaves when you exceed the rate limits, and how to respond if limits are exceeded.

Max data points per minute (DPM)

Data points per minute refers to the per minute rate at which individual metric values are sent to the Metric API. When the maximum DPM limit is exceeded for an account, the New Relic Metric API returns a 429 response for the remainder of the minute. The response will include a Retry-After header indicating how long to wait in seconds before re-submitting or sending new data.

To resolve this issue, either reduce the number of data points you are sending, or request a rate limit increase. You can request a rate limit increase by contacting your New Relic sales representative or e-mailing rate-limit-request@newrelic.com with your account ID(s) and requested limits.

Max unique timeseries per account per day

A timeseries is a single, unique combination of a metric name and any attributes assigned to that metric. For example, there's a CPU utilization metric with a single attribute hostname that's sent from 10 different hosts. This equals 10 distinct values for the hostname attribute, and 10 unique metric timeseries.

If the per day unique metric timeseries (cardinality) limit is exceeded during a 24 hour period, the endpoint will continue to receive and store raw metric data. However, New Relic will stop creating additional aggregate rollups (1 minute, 5 minutes, etc.) for the remainder of the 24 hour period. (These rollups are used used by default for querying time windows longer than 60 minutes.)

You can continue to query your data when such a violation occurs by specifying a 60 minute or shorter time window or specifying the RAW keyword as described in view and query your metrics. This can be helpful in identifying potential causes for the violation.

Max payloads per minute

If you make more than 10k POST requests to the Metric API endpoint within a minute, the endpoint will return a 429 response for the remainder of the minute. The response will include a Retry-After header indicating how long to wait in seconds before re-submitting or sending new data.

In general, if you hit this limit, you should consider creating larger payloads. To do this, combine more data points into each request to reduce the number of POSTs that are necessary. If this is not an option, you can request a rate limit increase by contacting your New Relic sales representative or e-mailing rate-limit-request@newrelic.com with your account ID(s) and requested limits.

Restricted attributes

These attributes are restricted by the New Relic platform. Any values submitted with these keys in the attributes section of a metric data point will cause the data point to be dropped, or the value to be omitted or overwritten:

attribute description
newrelic.source This resets to the value metricAPI.
metricName This resets to the name value passed into each data point. This allows name to be an attribute key.
endTimestamp timestamp and interval.ms will be converted to an endTimestamp for the data point.

Additional restrictions include:

  • You cannot pass the same value for metric and attribute name. In the following example, the metric is invalid because the metric is named service.errors.all and there is an attribute service.errors.all.

    Example: metric value used as an attribute
    [
      {
        "metrics": [
          {
            "name": "service.errors.all",
            "type": "count",
            "value": 15,
            "timestamp": 1531414060739,
            "interval.ms": 10000,
            "attributes": {
              "service.response.statuscode": "400",
              "service.errors.all": "test",
              "service.name": "foo"
            }
          }
        ]
      }
    ]
    						
  • The metric API inherits some reserved words from New Relic Insights, including accountID, appId, and eventType. Additionally, the syntax terms for NRQL are restricted if you do not backtick them. For a full list, see Reserved words: NRQL syntax terms.

  • All keys used within the metric JSON cannot be attribute keys. This includes interval.ms, timestamp, value, common, min, max, count, sum, and metrics. The one exception is name which can be used as an attribute key.

For more help

Recommendations for learning more:

  • Browse New Relic's Explorers Hub for community discussions about New Relic's APIs.
  • Use your preferred search engine to find other New Relic resources.