Working with the New Relic REST API (v1) (deprecated)

Deprecated

Currently New Relic supports two versions of the REST API. Version 1 is deprecated and will eventually be replaced with the newer v2. No termination date has been announced. However, no further development or modifications are being made to v1.

Recommendation: Start new projects by referring to Getting started with API v2 and the New Relic REST API v2 examples. Also, begin migrating your v1 scripts to their v2 equivalent.

Video


[video link] For an overview of the New Relic's reporting, alerting, and API features, watch this video (approximately 1-1/2 minutes).

Setup

To use the REST API in any way, be sure to activate API access and get your API key from your account settings. For more information, see API key.

Then, from the command line, you can use:

curl -gH "x-api-key:REPLACE_WITH_YOUR_API_KEY" '<URL>'

OR

wget -qO- --header "x-api-key:REPLACE_WITH_YOUR_API_KEY" '<URL>'

From a Ruby program, use an http helper such as curb. Be sure to set the x-api-key header with every request.

Note: You may be able to use the newrelic_api Ruby gem to do some of these things natively. In this situation, be sure to first set:

NewRelicApi.api_key='REPLACE_WITH_YOUR_API_KEY'

Examples

Here are some practical examples to pull metric data with New Relic's REST API v1 by using the command line or Ruby. If you are looking for an exhaustive guide to using the REST API v1 with cross-linked information to the background methods in the newrelic_api Ruby gem, refer to the documentation for using New Relic's data API access methods.

Account ID (v1)

Many New Relic API calls require both an API key in the call header and an Account ID in the request URI. However, when requesting authorization from users to access New Relic APIs on their behalf, you only need to ask those users for their New Relic API key; you do not need to request their New Relic Account ID.

Make the following call, using only the API key in the header:

https://api.newrelic.com/api/v1/accounts.xml

New Relic will return the Account ID for that API key. The Account ID appears between data-access-key and license-key as id. For example:


<account>
   <allow-rails-core> false </allow-rails-core>\>
   <api-key> xxxxxxxxxxxxxxxxxxxxx </api-key>
   <data-access-key> xxxxxxxxxxxxxxxxxxxxx </data-access-key>
   <id type='integer'> 1234567 </id>
   <license-key> xxxxxxxxxxxxxxxxxxxxx </license-key>
   ...

Save the Account ID alongside the user's API key, and use them both in subsequent calls to New Relic's REST API.

Applications list (v1)

To get the list of applications you can query for your account:

curl -gH "x-api-key:REPLACE_WITH_YOUR_API_KEY" 'https://api.newrelic.com/api/v1/accounts/REPLACE_WITH_YOUR_ACCOUNT_ID/applications.xml'

OR in Ruby:

response = Curl::Easy.perform("https://api.newrelic.com/api/v1/accounts/REPLACE_WITH_YOUR_ACCOUNT_ID/applications.xml") do |curl|
        curl.headers["x-api-key"] = "REPLACE_WITH_YOUR_API_KEY"
end
puts response.body_str
Summary metrics (v1)

To get the summary metrics for an application:

curl -gH "x-api-key:REPLACE_WITH_YOUR_API_KEY" 'https://api.newrelic.com/api/v1/accounts/REPLACE_WITH_YOUR_ACCOUNT_ID/applications/REPLACE_WITH_YOUR_APP_ID/threshold_values.xml'

OR in Ruby:


response = Curl::Easy.perform("https://api.newrelic.com/api/v1/accounts/REPLACE_WITH_YOUR_ACCOUNT_ID/applications/REPLACE_WITH_YOUR_APP_ID/threshold_values.xml") do |curl|
        curl.headers["x-api-key"] = "REPLACE_WITH_YOUR_API_KEY"
end
puts response.body_str
Available metrics (v1)

To get the list of available metrics for an application:

curl -gH "x-api-key:REPLACE_WITH_YOUR_API_KEY" 'https://api.newrelic.com/api/v1/applications/REPLACE_WITH_YOUR_APP_ID/metrics.xml'

OR in Ruby:


response = Curl::Easy.perform("https://api.newrelic.com/api/v1/applications/REPLACE_WITH_YOUR_APP_ID/metrics.xml") do |curl|
        curl.headers["x-api-key"] = "REPLACE_WITH_YOUR_API_KEY"
end
puts response.body_str
End user Apdex metric per hour (v1)

Here is an example of how to get the end user Apdex metric (per hour) "Score" data for an application. This example uses December 15, 2011 (UTC).

curl -gH "x-api-key:REPLACE_WITH_YOUR_API_KEY" 'https://api.newrelic.com/api/v1/accounts/REPLACE_WITH_YOUR_ACCOUNT_ID/applications/REPLACE_WITH_YOUR_APP_ID/data.xml?metrics[]=EndUser/Apdex&field=score&begin=2011-12-15T00:00:00Z&end=2011-12-16T00:00:00Z'

OR in Ruby:

response = Curl::Easy.perform("https://api.newrelic.com/api/v1/accounts/REPLACE_WITH_YOUR_ACCOUNT_ID/applications/REPLACE_WITH_YOUR_APP_ID/data.xml?metrics[]=EndUser/Apdex&field=score&begin=2011-12-15T00:00:00Z&end=2011-12-16T00:00:00Z") do |curl|
        curl.headers["x-api-key"] = "REPLACE_WITH_YOUR_API_KEY"
end
puts response.body_str
End user Apdex metric summary (v1)

Here is an example of how to get the end user Apdex metric (summary) "Score" data for an application. This example uses December 15, 2011 (UTC).

curl -gH "x-api-key:REPLACE_WITH_YOUR_API_KEY" 'https://api.newrelic.com/api/v1/accounts/REPLACE_WITH_YOUR_ACCOUNT_ID/applications/REPLACE_WITH_YOUR_APP_ID/data.xml?metrics[]=EndUser/Apdex&field=score&summary=1&begin=2011-12-15T00:00:00Z&end=2011-12-16T00:00:00Z'

OR in Ruby:

response = Curl::Easy.perform("https://api.newrelic.com/api/v1/accounts/REPLACE_WITH_YOUR_ACCOUNT_ID/applications/REPLACE_WITH_YOUR_APP_ID/data.xml?metrics[]=EndUser/Apdex&field=score&summary=1&begin=2011-12-15T00:00:00Z&end=2011-12-16T00:00:00Z") do |curl|
        curl.headers["x-api-key"] = "REPLACE_WITH_YOUR_API_KEY"
end
puts response.body_str
Alerts (v1)

New Relic's REST API allows you to configure alert settings. This includes enabling and disabling alerts for applications and servers, as well as getting and setting alert thresholds.

User alert notification settings are also exposed. You can configure whether a user receives email alerts at the account level and tailor settings for individual applications. You can also specify which users receive weekly performance reports. For more information, see Alert API examples (v1).

Servers (v1)

You can use display_name at the server_settings API endpoint to view a list of settings for all servers, view a specific server's settings, or update a server's settings. Here is an example of the display_name setting using CURL:

curl -H "x-api-key:YOUR_API_KEY_HERE" -X POST -d "name=My-Hostname" https://api.newrelic.com/api/v1/accounts/1/servers/find.xml

For more information, see the individual server sections in New Relic's REST API (v1) documentation on Github.

Deployments (v1)

To record deployments, follow the online instructions:

  1. From the New Relic APM menu bar, select Applications > (selected app) > Events > Deployments.
  2. From the Deployments dashboard, select Show instruction.

Here is an example of using curl to send deployment information directly by HTTP with your API key and application ID:

curl -H "x-api-key:REPLACE_WITH_YOUR_API_KEY" -d "deployment[app_name]=REPLACE_WITH_YOUR_APP_NAME" https://api.newrelic.com/deployments.xml

For more information, see Deployments and New Relic's deployment API documentation on GitHub.

Metric data (v1)

If you want to take the performance data out of New Relic and use it in some way, you can use the metric data API. It will allow you to get most of the data used in New Relic charts for your own purposes. For more information, see:

For more help

Additional documentation resources include:

  • API key (creating, copying, or re-generating your API key from the New Relic user interface)
  • Extracting metric data (time slice averages and policy considerations for data aggregation)
  • Ruby gem's data API access methods (this includes a detailed description of the New Relic REST API v1, along with examples and ActiveResource helpers)

If you need additional help, get support at support.newrelic.com.