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.

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.

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:

Deployments

To record deployments with New Relic agents, and via REST API v2, see Deployment notifications. While both API v1 and v2 allow you to post new deployments, API v2 also allows you to retrieve a list of past deployments, and delete deployments.

Deployment procedures

To record a deployment with REST API v1, specify your API key and either an app_name or application_id parameter.

Here is an example of using cURL to record deployments via the API with an application_id and corresponding API key:

curl -H "x-api-key:YOUR_API_KEY"
-d "deployment[application_id]=YOUR_APP_ID"
-d "deployment[description]=This is an app id deployment" https://api.newrelic.com/deployments.xml

For Windows users, here are examples using PowerShell to send deployment information:

Invoke-RestMethod -uri https://api.newrelic.com/deployments.xml -Method Post -Headers @{"x-api-key"="REPLACE_WITH_YOUR_API_KEY"} -Body @{"deployment[application_id]"="REPLACE_WITH_YOUR_APP_ID"; "deployment[description]"="This is an app id deployment"}
Invoke-RestMethod -uri https://api.newrelic.com/deployments.xml -Method Post -Headers @{"x-api-key"="REPLACE_WITH_YOUR_API_KEY"} -Body @{"deployment[app_name]"="REPLACE_WITH_YOUR_APP_NAME"; "deployment[description]"="This is an app name deployment"}
Deployment limitations

There are limits to the length of each field when recording a deployment:

  • deployment[app_name]: Limited to a single name per request
  • deployment[application_id]: Limited to a single id per request
  • deployment[description]: Maximum 65535 characters
  • deployment[changelog]: Maximum 65535 characters
  • deployment[user]: Maximum 31 characters
  • deployment[revision]: Maximum 127 characters

Also, when recording deployments via cURL:

  • Do not include line breaks or carriage returns. These will cause errors or fail to report.
  • Do not include a semicolon ; in the character string. Semicolons denote the end of a line in the CLI, and your command will be truncated.

Alerts and API v1

The API examples in this document apply only to using the REST API v1 with New Relic's existing alerting system. They are not compatible with New Relic Alerts.

Applications settings

This creates a list of settings for all apps:


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

Output includes:

  • Application ID
  • Application name
  • Indicator whether alerts are enabled or not
  • Current application Apdex
  • Current browser monitoring Apdex
  • Indicator whether page load timing (sometimes referred to as real user monitoring or RUM) is enabled or not
Applications thresholds

This creates a list of alert thresholds for an app's Apdex and error rate settings:

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/thresholds.xml' 
Servers

This creates a list of all servers, including server ID and host name:

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

This creates a list of settings for all servers:

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

Output includes:

  • Server ID
  • Host name
  • Indicator whether alerts are enabled or not
  • Name that appears in the Servers UI
Server thresholds

This creates a list of thresholds for a specific server, including threshold ID, :

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

Output includes:

  • Threshold ID
  • Threshold type (SystemCPU, SystemDiskIO, etc.)
  • Caution and Critical values
Users

This creates a list of all users:

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

Output includes:

  • User ID
  • Email address
  • Indicator whether to send weekly report
  • Indicator whether to send alert email

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.