Plugin API specification

The API for New Relic Plugins supports one operation, a POST of metric data. New Relic Partners and customers can use this API to send their own metric data to New Relic Plugins and view data received from the API in the New Relic Plugins user interface.

To enhance the presentation of your metric data, use the plugin developer tools in the New Relic Plugins application to develop customized dashboards. For more information, see Working with plugin dashboards.


Requests are authenticated using the X-License-Key request header, which is set to the account license key.


Data can be sent in the following encoding formats:

  • identity
  • deflate
  • gzip

If data is sent compressed, make sure the Content-Encoding header specifies the type of encoding.

Metric data POST

Metric data is sent as an HTTP POST of JSON data using this URI:

The MIME-type for the POST is application/json.

For details on the JSON syntax, see Metric data for the Plugin API.

POST frequency and limitations

The New Relic Plugins product is designed to receive a continuous stream of metrics at a certain maximum speed, and to present this information on useful charts. The recommended frequency for sending data to New Relic Plugins is to send 60 seconds worth of data once a minute. Agents sending data more frequently than twice a minute on average may be subject to enforced limits on the number of metrics being saved.

The following are recommended soft limits. Requests smaller than this will work; requests larger than this are subject to rejection or automatic data aggregation. As a hard cap, the total size of the POST payload should be no larger than 1MB.

Type Limit Description
Components 500 Number of distinct components currently tracked. Please note this is a per POST limit only. More than 500 components are able to report to an account simultaneously.
Metrics per component 10,000 Total number of unique metrics per component. Take precautions to ensure metric names are not generated too dynamically. Even if the number of metrics being sent in each individual post is small, over time they may add up to a large number of unique metrics. When the number of metrics for a given component exceeds this limit, the server may start aggregating metrics together by globbing segments of the metric name with an asterisk (*).
Metrics per post 20,000 Number of metrics sent per post. A post may send data for multiple components in a single request as long as the total number of metrics in the request does not exceed this limit.
Frequency of post 2 per minute Frequency of update. Agents are expected to send data no more frequently than 1 per minute.

If the metric is "expensive" to calculate and does not change quickly, consider writing your plugin agent so that it skips some polling cycles to retrieve data and then sends the last value. This produces better results for your plugin users' dashboards.


At this time, the Plugin API does not support New Relic's REST API, and vice versa. However, you can use New Relic's REST API (v2) to extract plugin data. For a list with links to procedures and examples, see Plugin Examples (v2).

For more help

Additional documentation resources include:

Recommendations for learning more: