Getting started with the New Relic REST API

This is a set of practical examples to pull metric data with New Relic's REST API by using Ruby or the command line. If you are looking for an exhaustive guide to using the REST API with crosslinked information to the background methods in the newrelic_api Gem, refer to the documentation for using our Ruby gem's data API access methods.

Note: The REST API (sometimes referred to as the New Relic API version 1) is not the same as version 2 (sometimes referred to as the API Explorer). For more information, see Getting started with New Relic's API Explorer.

Video


Video 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 like curb. Be sure to set the x-api-key header with every request.

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

NewRelicApi.api_key='REPLACE_WITH_YOUR_API_KEY'

Account ID

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

Applications list

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

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

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

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

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

Alert API

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.

Servers

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 in New Relic's REST API using CURL:

  curl -H "x-api-key:YOUR_API_KEY_HERE" -X PUT -d "display_name=My Hostname" https://api.newrelic.com/api/v1/accounts/1/server_settings/222.xml

For more information, see the individual server sections in the REST API beginning with View servers.

Recording deployments

To record deployments, follow the online instructions:

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

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 the Deployment API documentation on GitHub.

Metric data

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

For more help

Additional documentation resources include:

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