List your server ID and metric data (v2)

Here are examples of how to use the New Relic REST API (v2) to get metric names and summary data for a specific server ID and API key.

When acquiring data, the values returned may be affected by the time period you specify and the way the data is stored. For more information, see Extracting metric timeslice data.

View your server IDs

If you want to use New Relic's REST API Explorer to obtain the same information as this example, see Retrieving metric timeslice data for your app (Explorer).

To view your server IDs:

curl -X GET 'https://api.newrelic.com/v2/servers.json' \
     -H "X-Api-Key:${API_KEY}" -i 

The output will be an array of data where each element is a server and the summary data associated with it. For example, here are the first two elements for server ID 2725583 ("api1.com"), which is currently not reporting, and 2190582 ("production1.center.com") which is currently reporting:

{
  "servers": [
    {
      "id": 2725583,    <---<<< SERVER_ID
      "account_id": XX,
      "name": "api1.com",
      "host": "api1.com",
      "reporting": false
    },
    {
      "id": 2190582,   <---<<< SERVER_ID
      "account_id": XX,
      "name": "production1.center.com",
      "host": "production1.center.com",
      "reporting": true,
      "last_reported_at": "2014-08-21T21:26:54+00:00",
      "summary": {
        "cpu": 6.07,
        "cpu_stolen": 0,
        "disk_io": 0.1,
        "memory": 8.45,
        "memory_used": 2846883840,
        "memory_total": 33710669824,
        "fullest_disk": 28.8,
        "fullest_disk_free": 13691000000
      }
    },
    ...
List by server label

If there is a label associated with the server, find the servers and IDs using the filter[] options like this:

curl -X GET 'https://api.newrelic.com/v2/servers.json' \
     -H 'X-Api-Key:${API_KEY}' -i \
     -G -d 'filter[labels]=Env:Test' 

The output will be similar to the previous example, but it will list all the servers with the label you specify. The REST API only allows you to use one label in this filter. To view this in the API Explorer, select Servers > List.

List by server name

To find the server ID if you know the server name:

curl -X GET 'https://api.newrelic.com/v2/servers.json' \
     -H "X-Api-Key:${API_KEY}" -i \
     -d 'filter[name]=production1.center.com'

The output will be the same as the previous example but for the single server name specified. To view this in the API Explorer, select Servers > List.

List by host name

To find the server ID if you know the host name:

curl -X GET 'https://api.newrelic.com/v2/servers.json' \
     -H 'X-Api-Key:${API_KEY}' -i \
     -G -d 'filter[host]=Worker1.apm' 

The output will be the same as the previous example but for the single host name specified. To view this in the API Explorer, select Servers > List.

List servers reporting in the last ten hours

To view a list of servers reporting in the last ten hours, set filter[reported] to true:

curl -X GET 'https://api.newrelic.com/v2/servers.json' \
     -H 'X-Api-Key:${API_KEY}' -i \
     -G -d 'filter[reported]=true' 

The output will be the same as the previous example, but the list will contain only those servers that have reported in the last ten hours. (You cannot change the ten-hour reporting period.) To view this in the API Explorer, select Servers > List.

List servers sorted by their health status

To view a list of servers sorted according to their health status, set the sort[health_status] to true:

curl -X GET 'https://api.newrelic.com/v2/servers.json' \
     -H 'X-Api-Key:${API_KEY}' -i \
     -G -d 'sort[health_status]=true' 

The output will be the same as the previous example, but the list will be sorted in the following order, according to the health_status value being reported for each server:

  1. Red
  2. Orange
  3. Green
  4. Light green
  5. Gray (not reporting)
  6. Unavailable

To view this in the API Explorer, select Servers > List.

Pagination control for the sorted list

If the returned list of servers exceeds the number displayed on a single page, the data will be paginated. To view the total list you must request each page. However, each time a new page is requested, any server's health status may have changed.

To solve this potential problem, when the sort[health_status] options is set to true, the response will provide the first page of servers. The response's link header will also include a token that identifies the sorted response. When the token is submitted with a new page number in subsequent requests, it assures that the original sort order will be returned. This token is valid for two minutes after creation.

Example command that creates page 1 (default) output:

curl -X GET 'https://api.newrelic.com/v2/servers.json' \
     -H 'X-Api-Key:${API_KEY}' -i \
     -G -d 'sort[health_status]=true' 

Example link header for the list (wrapped for display purposes), showing the token and indicating there are nine pages:

Link: <https://api.newrelic.com/v2/servers.json?page=2&sort%5Bhealth_status%5D=true&sort%5Btoken%5D=928afe7a5b5a23e6a261c1a51eb05b072ae8649b>; rel="next", 
      <https://api.newrelic.com/v2/servers.json?page=9$amp;sort%5Bhealth_status%5D=true&sort%5Btoken%5D=928afe7a5b5a23e6a261c1a51eb05b072ae8649b>; rel="last"

Example of using the token to obtain page=3:

curl -X GET 'https://api.newrelic.com/v2/servers.json' \
     -H 'X-Api-Key:${API_KEY}'' -i \
     -G -d 'sort[health_status]=true&sort[token]=928afe7a5b5a23e6a261c1a51eb05b072ae8649b&page=3' 

Example of the link header returned for page 3 of the nine-page listing (wrapped for display purposes):

Link: <https://api.newrelic.com/v2/servers.json?page=1&sort%5Bhealth_status%5D=true&sort%5Btoken%5D=928afe7a5b5a23e6a261c1a51eb05b072ae8649b>; rel="first", 
      <https://api.newrelic.com/v2/servers.json?page=2&sort%5Bhealth_status%5D=true&sort%5Btoken%5D=928afe7a5b5a23e6a261c1a51eb05b072ae8649b>; rel="prev", 
      <https://api.newrelic.com/v2/servers.json?page=4&sort%5Bhealth_status%5D=true&sort%5Btoken%5D=928afe7a5b5a23e6a261c1a51eb05b072ae8649b>; rel="next", 
      <https://api.newrelic.com/v2/servers.json?page=9&sort%5Bhealth_status%5D=true&sort%5Btoken%5D=928afe7a5b5a23e6a261c1a51eb05b072ae8649b>; rel="last"

View metric names for your server

You can view all available metric names or a specific metric name for your server.

Follow the metric name guidelines when listing metric names.

List all metric names

To view the metric names available for your server:

curl -X GET "https://api.newrelic.com/v2/servers/${SERVER_ID}/metrics.json" \
     -H "X-Api-Key:${APIKEY}" -i

The output will be similar to the following. This shows three of the many metric names available and their values. These lists can be long, so the output is paginated. You may need to look at several pages before locating your metric name.

{
  "metrics": [
    {
      "name": "Agent/MetricsReported/count",
      "values": [
        "average_response_time",
        "calls_per_minute",
        "call_count",
        "min_response_time",
        "max_response_time",
        "average_exclusive_time",
        "average_value",
        "requests_per_minute",
        "standard_deviation"
      ]
    },
    {
      "name": "ProcessSamples/clyde/bash",
      "values": [
        "average_response_time",
        "calls_per_minute",
        "call_count",
        "min_response_time",
        "max_response_time",
        "average_exclusive_time",
        "average_value",
        "requests_per_minute",
        "standard_deviation"
      ]
    },
    ...
    {
      "name": "System/Network/eth0/Transmitted/packets/sec",
      "values": [
        "per_second",
        "total",
        "min_per_second",
        "max_per_second",
        "standard_deviation"
      ]
    },
    ...
List by metric name

If you know your metric name, you can view it directly by specifying the name. This example shows how to obtain the values from the metric name System/Memory/Used/bytes:

curl -X GET 'https://api.newrelic.com/v2/servers/${SERVER_ID}/metrics.json' \
     -H 'X-Api-Key:${API_KEY}' -i \
     -d 'name=System/Memory/Used/bytes'

View your server's metric timeslice data values

To view the metric timeslice data available for your application:

curl -X GET "https://api.newrelic.com/v2/servers/${SERVER_ID}/metrics/data.json" \
     -H "X-Api-Key:$API_KEY" -i \
     -d 'names[]=System/Memory/Used/bytes&values[]=average_response_time'

This shows a request for the average_response_time. By default the data will be output for each minute during the latest 30 minutes. You can specify a time range and average or summarize the metric values over the time range.

For more help

Additional documentation resources include information and detailed examples for requesting server metric data via the REST API.

Discuss New Relic Servers in the New Relic Online Technical Community! Troubleshoot and ask questions, or discuss Servers for Linux or Servers for Windows in detail.

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