Extract metric timeslice data

New Relic's REST API allows you to extract metric timeslice data directly from the New Relic database. However, the API is not intended for bulk data extraction of minute by minute data points. This document summarizes what to expect for the extracted metric timeslice data.

Time based data

All time values returned by the REST API and the API Explorer are UTC (Universal Time Coordinated). Be sure to adjust the time values for data collection as necessary.

Time range considerations

The minimum time range for data requests is one minute (60 seconds). Requests for anything less will result in a 422 status code and no data will be returned. New Relic only collects data at one minute intervals.

The API uses the same mechanism for requesting data as the UI: it depends on the time range for the data you request. The objective is to optimize the number of data points returned and provide an easily digestible graph and report.

For example:

  • If you request data from a time range of three hours or less, the API returns the one-minute data values originally collected.
  • If you increase the time range to greater than three hours, the data values returned will be an average for two minutes.
  • If you increase the time range to over six hours, the data values returned will be an average for five minutes, and so on.

If the initial time for a requested time range is older than eight days, ten evenly spaced data points will be returned for any time range less than four days in length.

Here is a summary of the metric value retrieval for the time ranges available.

Between this time... and this time Granularity of collected data
≤ 8 days > 8 days
≤ 3 hours 1 minute 10 evenly spaced
data points
> 3 hour ≤ 6 hours 2 minutes
> 6 hours ≤ 14 hours 5 minutes
> 14 hours ≤ 24 hours 10 minutes
> 1 day (24 hrs) ≤ 4 days (96 hrs) 30 minutes
> 4 days ≤ 7 days 1 hour 1 hour
> 7 days ≤ 3 weeks 3 hours 3 hours
> 3 weeks ≤ 6 weeks 6 hours 6 hours
> 6 weeks ≤ 9 weeks 12 hours 12 hours
> 63 days 3 days 3 days

When the start time for a requested time range is older than eight days, data has been aggregated or averaged to one hour periods due to the data aggregation schedule. This means that for any one hour period, only a single data value is available. Obtaining data at less than an hourly period in the time range would cause oversampling, resulting in duplicate values being returned. Returning only ten values prevents oversampling and presents a smoother chart, which eliminates a possibly misleading "plateau" effect.

Controlling time period output

Sometimes the output data's granularity may be too fine, or the time period for the data returned may be too short. To control this, include the period= parameter in the query command as the number of seconds you want each time period to report. Make sure your specifications follow New Relic's data aggregation schedules.

Example #1: Following New Relic's table summarizing granularity of collected data, the following API call would normally return data in 30-minute periods, since the request is for 4 days (from=2015-02-13 and to=2015-02-17). By adding period=3600, the data will be returned as 60-minute periods.

curl -X GET 'https://api.newrelic.com/v2/applications/${APPID)/metrics/data.xml' \
     -H 'X-Api-Key:${API_KEY}' -i \
     -d'names[]=CPU/User+Time&from=2015-02-13T04:00:00+00:00&to=2015-02-17T04:00:00+00:00&period=3600'

You cannot specify a period smaller than the default for the time range you are requesting. For example:

  • In the command example above, you can request 1-hour periods, since that is greater than the default (half hour) granularity for the time range.
  • In the command example above, you cannot request 1-minute periods, since that is less than the default (half hour) granularity for the time range.

Example #2: If you request a range > 7 days but ≤ 3 weeks, where the default period is 3 hours, you can specify periods such as 6, 12, or 24 hours. However, you cannot request 1-hour periods, because that is less than the default (3 hours).

Data aggregation

The ability to obtain data depends on your New Relic subscription level and your account level's data aggregation schedule.

Extracting non-existent metric timeslice data

Situations may arise where non-existent metric names are requested. For example:

  • The metric timeslice data has not been created for one application, but exists for another. When the same metric extraction query is used on both of these applications, it will not be located for one.
  • The metric name was incorrectly specified.

Metric values that have existed in the past, but are no longer collected, will return a zero value.

A successful response will include a 200 status code and metadata about the request. The metadata will contain the names of the metrics requested and the status of the request for those names.

Response Metadata Description Response Metric Data
metrics_not_found Lists all metric names for which matching data was not found in the requested time period. Metric timeslice data will not be returned for these metrics
metrics_found Lists all metric names for which matching data was found in the requested time period. Metric timeslice data will be returned for these metrics

Here is an example of output for a valid metric name, HttpDispatcher.

HTTP/1.1 200 OK
etag: "0dc87c63d8dff6b1a9714bdf7531ec09"
Content-Type: application/json
cache-control: max-age=0, private, must-revalidate
{
  "metric_data": {
    "from": "2016-01-28T18:06:06+00:00",
    "to": "2016-01-28T18:36:06+00:00",
    "metrics_not_found": [], <---<<< INDICATES NO INVALID METRIC NAMES REQUESTED
    "metrics_found": [
      "HttpDispatcher"       <---<<< INDICATES THIS METRIC NAME WAS VALID
    ],
    "metrics": [             <---<<< DATA RETURNED
      {
        "name": "HttpDispatcher",
        "timeslices": [
          {
            "from": "2016-01-28T18:03:00+00:00",
            "to": "2016-01-28T18:04:00+00:00",
            "values": {
              "average_response_time": 364,
              "calls_per_minute": 99800,
              "call_count": 99770,
              "min_response_time": 3.5,
              "max_response_time": 85000,
              "average_exclusive_time": 0,
              "average_value": 0.364,
              "total_call_time_per_minute": 36300,
              "requests_per_minute": 99800,
              "standard_deviation": 1900,
              "average_call_time": 364
            ...

Here is an example of output for a invalid metric name, Foo.

HTTP/1.1 200 OK
etag: "e51782cf7c5a5596139a7f5340c3de23"
Content-Type: application/json
cache-control: max-age=0, private, must-revalidate
{
  "metric_data": {
    "from": "2016-01-28T18:06:33+00:00",
    "to": "2016-01-28T18:36:33+00:00",
    "metrics_not_found": [
      "Foo"                   <---<<< INDICATES THIS METRIC NAME WAS INVALID
    ],
    "metrics_found": [],      <---<<< INDICATES NO VALID METRIC NAMES FOUND
    "metrics": []             <---<<< NO DATA RETURNED
  }
}

For more help

Additional documentation resources include:

Recommendations for learning more: