Use the synthetics REST API to create and manage synthetic monitors of all types: ping, simple browser, scripted browser, and API test monitors. All synthetic monitoring data is available via the REST API.

To use the synthetics REST API, you must have a user role that allows that capability and a .

For an overview of all our available APIs, see Intro to APIs. If you haven't already, create your free New Relic account below to start monitoring your data today.

Important

You can now manage your synthetic monitors (including certificate check monitors, step monitors, and broken links monitors) with our NerdGraph API.

Features

The newest version of the synthetic monitoring API (v3) adds these features:

Synthetic monitoring API (v3)	Features
Options field for POST and PUT request	You can specify the options for `SIMPLE` and `BROWSER` type monitors, similar to the way these options are available in the UI.
PATCH request	You can update only the fields of a monitor you want to change, rather than having to specify the entire monitor entity in a PUT. You can also specify the `OPTION`, assuming you are using the appropriate type of monitor.
More detail with 400 `Bad Request` errors	As of v3, the synthetic monitoring API attempts to return as much information as possible when a validation failure occurs. This will help you figure out what might be wrong with the request. The API runs all validations and returns any failed validation messages, rather than failing on the first validation error as occurred in previous API versions.
Pagination	Large API responses are properly paginated.

You can also use NRQL queries to analyze past changes made via the API.

Monitor types in API

These are the monitor types and how they're referred to in the API:

Monitor type	API name
Ping	`SIMPLE`
Simple browser	`BROWSER`
Scripted browser	`SCRIPT_BROWSER`
API test	`SCRIPT_API`

Use the API

To use the synthetic monitoring REST API, you must have the ability to manage synthetics monitors and use a user key (the REST API key won't work).

This API can be used for all synthetic monitors. (Additional API methods for scripted browser and API test monitors are also available to update the script associated with those monitors.) All synthetic monitoring data is available via the API. API examples show curl commands.

For US-based accounts, use the following endpoint:

https://synthetics.newrelic.com/synthetics/api

For EU-based accounts, use the following endpoint:

https://synthetics.eu.newrelic.com/synthetics/api

Caution

The synthetic monitoring REST API limits an account's rate of requests to three requests per second. Requests made in excess of this threshold will return a 429 response code.

To view a list of all the monitors in your New Relic account, send a GET request to $API_ENDPOINT/v3/monitors. For example:

curl -v \
     -H "Api-Key:$API_KEY" $API_ENDPOINT/v3/monitors

A successful request will return a 200 OK response. The data returned will be a JSON object in the following format:

{
    "monitors": [
        {
        "id": "2a1bc369-7654-489d-918e-f6g135h7i2jk",
        "name": "monitor1",
        "type": "BROWSER",
        "frequency": 60,
        "uri": "http://example.com",
        "locations": [
            "AWS_US_WEST_1"
                ],
        "status": "DISABLED",
        "slaThreshold": 7,
        "options": {},
        "modifiedAt": "2016-09-26T23:12:46.981+0000",
        "createdAt": "2016-09-26T23:12:46.981+0000",
        "userId": 0,
        "apiVersion": "0.2.2"
        }
    ],
    "count": 1
}

Query arguments:

offset: The monitor count offset. Defaults to 0. For example, if you have 40 monitors and you use an offset value of 20, it will return monitors 21-40.
limit: The number of results per page, maximum 100. Defaults to 50.

You can include these in your curl command as follows:

curl -v \
     -H "Api-Key:$API_KEY" $API_ENDPOINT/v3/monitors \
     -G -d 'offset=20&limit=100'

The headers include a Link to help you easily page your monitors. For example:

<https://synthetics.newrelic.com/synthetics/api/v3/monitors/?offset=0&limit=20>; rel="first", <https://synthetics.newrelic.com/synthetics/api/v3/monitors/?offset=40&limit=20>; rel="last"

To view a single synthetic monitor, send a GET request to $API_ENDPOINT/v3/monitors/$MONITOR_ID.

curl -v \
     -H "Api-Key:$API_KEY" $API_ENDPOINT/v3/monitors/$MONITOR_ID

A successful request will return a 200 OK response. The data returned will be a JSON object in the following format:

{
  "id": UUID,
  "name": string,
  "type": string,
  "frequency": integer,
  "uri": string,
  "locations": array of strings,
  "status": string,
  "slaThreshold": double,
  "userId": integer,
  "apiVersion": string
}

An invalid monitor ID will return 404 Not Found: The specified monitor doesn't exist.

To add a new monitor to your Synthetics account, send a POST request to $API_ENDPOINT/v3/monitors with a JSON payload that describes the monitor.

All fields in the following example are required unless stated otherwise:

{
"name": string [required],
"type": string (SIMPLE, BROWSER, SCRIPT_API, SCRIPT_BROWSER) [required],
"frequency": integer (minutes) [required, must be one of 1, 5, 10, 15, 30, 60, 360, 720, or 1440],
"uri": string [required for SIMPLE and BROWSER type],
"locations": array of strings [at least one required],
"status": string (ENABLED, MUTED, DISABLED) [required],
"slaThreshold": double,
"options": {
  "validationString": string [only valid for SIMPLE and BROWSER types],
  "verifySSL": boolean (true, false) [only valid for SIMPLE and BROWSER types],
  "bypassHEADRequest": boolean (true, false) [only valid for SIMPLE types],
  "treatRedirectAsFailure": boolean (true, false) [only valid for SIMPLE types]
  }
}

In addition, to add the script for a scripted monitor via the REST API, call an additional API endpoint to send the script for the monitor just created. If you are using private locations with verified script execution enabled, see script locations with verified script execution.

Replace the synthetic monitoring REST API attributes in the following example with your specific values:

curl -v \
     -X POST -H "Api-Key:$API_KEY" \
     -H 'Content-Type: application/json' $API_ENDPOINT/v3/monitors \
     -d '{ "name" : "monitor1", "frequency" : 15, "uri" : "http://my-uri.com", "locations" : [ "AWS_US_WEST_1" ], "type" : "browser", "status" : "enabled", "slaThreshold" : "1.0"}'

A successful request will return a 201 Created response, with the URI of the newly-created monitor specified in the location header. Possible error codes include:

400 Bad Request: One or more of the monitor values is invalid, or the format of the request is invalid. For example: the frequency is out of bounds or one or more of the specified locations is invalid. (See the error message in the body of the response.)
402 Payment Required: Creating the monitor will increase your scheduled checks past your account's purchased check limit.

To update an existing monitor in New Relic, send a PUT request to $API_ENDPOINT/v3/monitors/$MONITOR_ID. In addition, for scripted monitors, follow the procedures to update the BASE64 encoded script.

All fields are required. However, the TYPE of the monitor cannot be changed.

Use a specific monitor ID, and replace the synthetic monitoring REST API attributes with your specific values.

curl -v \
     -X PUT -H "Api-Key:$API_KEY" \
     -H 'Content-Type: application/json' $API_ENDPOINT/v3/monitors/$MONITOR_ID \
     -d '{ "name" : "updated monitor name", "type": "monitor type", "frequency" : 15, "uri" : "http://my-uri.com/", "locations" : [ "AWS_US_WEST_1" ], "status" : "enabled", "slaThreshold": "7.0" }'

PUT requests are intended to replace target entities, so all attributes required in the JSON payload when creating a new monitor are also required when updating an existing monitor.

A successful request will return a 204 No Content response, with an empty body. Possible error codes include:

400 Bad Request: One or more of the monitor values is invalid, or the format of the request is invalid. For example, the frequency is out of bounds or one or more of the specified locations is invalid. (See the error message in the body of the response.)
404 Not Found: The specified monitor does not exist.

To patch an existing monitor in New Relic, send a PATCH request to $API_ENDPOINT/v3/monitors/$MONITOR_ID.

Use a specific monitor ID, and replace the synthetic monitoring REST API attributes with your specific values.

curl -v \
     -X PATCH -H "Api-Key:$API_KEY" \
     -H 'Content-Type: application/json' $API_ENDPOINT/v3/monitors/$MONITOR_ID \
     -d '{ "name" : "updated monitor name" }'

PATCH requests are intended to update individual attributes of your synthetic monitors rather than updating the entire entity, so you may provide only the attributes you want to update.

A successful request will return a 204 No Content response, with an empty body. Possible error codes include:

400 Bad Request: One or more of the monitor values is invalid, or the format of the request is invalid. For example, the frequency is out of bounds, or one or more of the specified locations is invalid. (See the error message in the body of the response.)
404 Not Found: The specified monitor does not exist.

To delete an existing monitor in synthetic monitoring, send a DELETE request to $API_ENDPOINT/v3/monitors/$MONITOR_ID:

curl -v \
     -H "Api-Key:$API_KEY" \
     -X DELETE $API_ENDPOINT/v3/monitors/$MONITOR_ID

A successful request will return a 204 No Content response, with an empty body. An unsuccessful request will return the response 404 Not Found: The specified monitor does not exist.

Script API for scripted browser and API test monitors

In addition to the general API, there are several API methods for the scripted browsers (SCRIPT_BROWSER) and API test browsers (SCRIPT_API). These examples show curl commands.

To view the script associated with a specific SCRIPT_BROWSER or SCRIPT_API in your account's synthetic monitors, send a GET request to $API_ENDPOINT/v3/monitors/$MONITOR_ID/script. For example:

curl -v
     -H "Api-Key:$API_KEY"
     $API_ENDPOINT/v3/monitors/$MONITOR_ID/script

A successful request will return a 200 OK response. The data returned will be a JSON object in the following format:

{
  "scriptText": BASE64 encoded string
}

Possible error codes include:

403 Forbidden: The specified monitor is not of type SCRIPT_BROWSER or SCRIPT_API.
404 Not Found: The specified monitor doesn't exist or the script associated with the monitor doesn't exist.

To add a new scripted monitor to your synthetic monitors with the REST API:

Follow standard API procedures to add a new monitor, and identify the type as a SCRIPT_BROWSER or SCRIPT_API.
Update the new monitor with a BASE64 encoded version of the script to the $MONITOR_UUID/script endpoint.
For more information, refer to the example.
If you are using private locations with verified script execution enabled, see script locations with verified script execution.

To update the script associated with a specific SCRIPT_BROWSER or SCRIPT_API monitor, send a PUT request to $API_ENDPOINT/v3/monitors/$MONITOR_ID/script with a JSON payload that contains the scriptText (required).

scriptPayload='{"scriptText":BASE64 encoded string}'


curl -v -X PUT \
     -H "Api-Key:$API_KEY" \
     -H 'Content-Type: application/json' \
     $API_ENDPOINT/v3/monitors/$MONITOR_UUID/script \
     -d $scriptPayload

If you are using private locations with verified script execution enabled, see script locations with verified script execution.

A successful request will return a 204 No Content response with an empty body. Possible error codes include:

400 Bad Request: Invalid BASE64 encoded string for scriptText or hmac.
403 Forbidden: The specified monitor is not of the type SCRIPT_BROWSER or SCRIPT_API.
404 Not Found: The specified monitor does not exist.

When creating or updating monitors for private locations that have verified script execution turned on, you must use scriptLocations to set the password:

{
  "scriptText": BASE64 encoded String,
  "scriptLocations": [
    {
      "name": Location name,
      "hmac" BASE64 encoded String of SHA256 HMAC for location
    }
  ]
}

The password used to generate the HMAC string must match the password set for the private location. If you have multiple locations with Verified script execution enabled each location must have the HMAC calculated. When generating the HMAC string, use the SHA256 algorithm with the script and password.

Here's an example for the script:

var assert = require('assert');
assert.equal('1', '1');

This example uses password as the password for the scriptLocation:

curl -v
    -X PUT -H "Api-Key:$API_KEY"
    -H 'content-type: application/json'
    $API_ENDPOINT}/v3/monitors/$MONITOR_ID/script
    -d '{ "scriptText": "dmFyIGFzc2VydCA9IHJlcXVpcmUoJ2Fzc2VydCcpOw0KYXNzZXJ0LmVxdWFsKCcxJywgJzEnKTs=","scriptLocations": [ { "name": "my_vse_enabled_location", "hmac": "MjhiNGE4MjVlMDE1N2M4NDQ4MjNjNDFkZDEyYTRjMmUzZDE3NGJlNjU0MWFmOTJlMzNiODExOGU2ZjhkZTY4ZQ=="} ]}'

Important

You must remove the last newline character from both the script and the calculated HMAC value before encoding in BASE64.

Calculation steps:

Calculate the HMAC value from the script. One way is to use:
cat script | openssl dgst -sha256 -hmac "password" > hmac
Remove the newline character if one was added by openssl.
Encode the HMAC in BASE64 without line breaks.

Scripted browser example

Here is an example of using New Relic's REST API and the bash script to create a scripted browser monitor.

The following example shows curl commands to create a scripted browser monitor.

At the top of the script, replace the variables with your specific values.

For the scriptfile variable, identify the filename for the script to be created. Here is a sample script that can be saved as sample_synth_script.js to use in the example:

var assert = require("assert");
$browser.get("http://example.com").then(function(){ 
  // Check the H1 title matches "Example Domain" 
  return $browser.findElement($driver.By.css("h1")).then(function(element){ 
    return element.getText().then(function(text){ 
      assert.equal("Example Domain", text, "Page H1 title did not match"); 
    }); 
  }); 
}).then(function(){ 
  // Check that the external link matches "http://www.iana.org/domains/example" 
  return $browser.findElement($driver.By.css("div > p > a")).then(function(element){ 
    return element.getAttribute("href").then(function(link){ 
      assert.equal("http://www.iana.org/domains/example", link, "More information link did not match"); 
    }); 
  }); 
});

This example shows the bash script that will create the SCRIPTED_BROWSER monitor.

Tip

In some cases you may want to use -w 0, which will disable line wrapping: base64 -w 0 $scriptfile

#!/bin/bash

# API key from your account settings
API_KEY=''
# Other attributes found at https://docs.newrelic.com/docs/apis/synthetics-rest-api/monitor-examples/attributes-synthetics-rest-api#api-attributes
monitorName='Test API Script'
monitorType='SCRIPT_BROWSER'
frequency=1440
locations='"AWS_US_WEST_1", "AWS_US_EAST_1"'
slaThreshold=7.0
# Location of the file with your script
scriptfile=sample_synth_script.js

# Test that the script file exists (does not validate content)
if [ -e "$scriptfile" ]
then
  script=$(cat "$scriptfile")

  payload="{  \"name\" : \"$monitorName\", \"frequency\" : $frequency,    \"locations\" : [ $locations ],   \"status\" : \"ENABLED\",  \"type\" : \"$monitorType\", \"slaThreshold\" : $slaThreshold, \"uri\":\"\"}"
  echo "Creating monitor"

  # Make curl call to API and parse response headers to get monitor UUID
  shopt -s extglob # Required to trim whitespace; see below
  while IFS=':' read key value; do
    # trim whitespace in "value"
    value=${value##+([[:space:]])}; value=${value%%+([[:space:]])}
    case "$key" in
        location) LOCATION="$value"
                ;;
        HTTP*) read PROTO STATUS MSG <<< "$key{$value:+:$value}"
                ;;
    esac
  done < <(curl -sS -i  -X POST -H "Api-Key:$API_KEY" -H 'Content-Type:application/json' https://synthetics.newrelic.com/synthetics/api/v3/monitors -d "$payload")

  # Validate monitor creation & add script unless it failed
  if [ $STATUS = 201 ]; then
    echo "Monitor created, $LOCATION "
    echo "Uploading script"
      # base64 encode script
      encoded=`echo "$script" | base64`
      scriptPayload="{\"scriptText\":\"$encoded\"}"
        curl -s -X PUT -H "Api-Key:$API_KEY" -H 'Content-Type:application/json' "$LOCATION/script" -d $scriptPayload
        echo "Script uploaded"
  else
    echo "Monitor creation failed"
  fi

else
  echo "script file not found, not creating monitor"
fi

Manage synthetic monitors via REST API

Important

Features

Monitor types in API

Use the API

Caution

Get all monitors

Get a specific monitor

Create a monitor

Update an existing monitor

Patch an existing monitor

Delete an existing monitor

Get a list of valid locations

Script API for scripted browser and API test monitors

Get monitor script

Add scripted monitor

Update monitor script

Using private location scripts with verified script execution

Important

Scripted browser example

Scripted browser API example

Bash script example

Tip