Manage scripted API monitors

New Relic allows you use NerdGraph to create scripted API monitors. Scripted API monitors execute custom JavaScript code to test APIs and backend services without a browser, making HTTP requests and validating responses programmatically. This tutorial provides examples of how to use the NerdGraph API to automate the creation of scripted API monitors.

Create a scripted API monitor

You can create a scripted API monitor using the syntheticsCreateScriptApiMonitor mutation. This mutation allows you to set up custom API testing that executes your JavaScript code to validate API endpoints.

Input parameters

Parameter	Data Type	Is it Required?	Description
`accountId`	Integer	Yes	Your New Relic account ID where the monitor will be created.
`monitor.locations.public`	Array	Yes	Array of public location identifiers where the monitor will run checks (e.g., `["US_EAST_1", "US_WEST_1"]`).
`monitor.name`	String	Yes	The display name for your scripted API monitor.
`monitor.period`	Enum	Yes	How often the monitor runs. Options: `EVERY_MINUTE`, `EVERY_5_MINUTES`, `EVERY_10_MINUTES`, `EVERY_15_MINUTES`, `EVERY_30_MINUTES`, `EVERY_HOUR`, `EVERY_6_HOURS`, `EVERY_12_HOURS`, `EVERY_DAY`.
`monitor.runtime.runtimeType`	String	Yes	The runtime type used by your monitor. `NODE_API` is the only accepted value.
`monitor.runtime.runtimeTypeVersion`	String	Yes	The runtime type version used by your monitor. `16.10` is the only accepted value.
`monitor.runtime.scriptLanguage`	String	Yes	The language used in your monitor. `JAVASCRIPT` is the only accepted value.
`monitor.script`	String	Yes	The JavaScript code that the monitor executes. This should be plain text, not base64 encoded. The script can use the $http object to make HTTP requests and perform API testing.
`monitor.status`	Enum	Yes	The monitor status. Options: `ENABLED` (monitor is active and performing checks), `DISABLED` (monitor is inactive).
`monitor.apdexTarget`	Float	No	The monitor's Apdex target in seconds, used to populate SLA reports. Defaults to 7.0 seconds.

Sample request

mutation {
 syntheticsCreateScriptApiMonitor(
 accountId: ACCOUNT_ID
 monitor: {
 locations: { public: ["LOCATION_1", "LOCATION_2"] }
 name: "YOUR_MONITOR_NAME"
 period: PERIOD
 runtime: {
 runtimeType: "RUNTIME_TYPE"
 runtimeTypeVersion: "RUNTIME_TYPE_VERSION"
 scriptLanguage: "SCRIPT_LANGUAGE"
 }
 script: "SCRIPT_CONTENT"
 status: STATUS
 apdexTarget: APDEX_TARGET
 }
 ) {
 errors {
 description
 type
 }
 }
}

Sample response

A successful response returns null for errors:

{
 "data": {
 "syntheticsCreateScriptApiMonitor": {
 "errors": null
 }
 }
}

If there are any issues creating the monitor, the errors array will contain objects with description and type fields explaining what went wrong.

Update a scripted API monitor

You can update an existing scripted API monitor using the syntheticsUpdateScriptApiMonitor mutation. This allows you to modify the configuration of a scripted API monitor that has already been created.

Input parameters

Parameter	Data Type	Is it Required?	Description
`guid`	String	Yes	The unique entity GUID of the monitor you want to update.
`monitor.locations.public`	Array	No	Array of public location identifiers where the monitor will run checks (e.g., `["US_EAST_1", "US_WEST_1"]`).
`monitor.name`	String	No	The updated display name for your scripted API monitor.
`monitor.period`	Enum	No	How often the monitor runs. Options: `EVERY_MINUTE`, `EVERY_5_MINUTES`, `EVERY_10_MINUTES`, `EVERY_15_MINUTES`, `EVERY_30_MINUTES`, `EVERY_HOUR`, `EVERY_6_HOURS`, `EVERY_12_HOURS`, `EVERY_DAY`.
`monitor.runtime.runtimeType`	String	No	The runtime type used by your monitor. `NODE_API` is the only accepted value.
`monitor.runtime.runtimeTypeVersion`	String	No	The runtime type version used by your monitor. `16.10` is the only accepted value.
`monitor.runtime.scriptLanguage`	String	No	The language used in your monitor. `JAVASCRIPT` is the only accepted value.
`monitor.script`	String	No	The JavaScript code that the monitor executes. This should be plain text, not base64 encoded.
`monitor.status`	Enum	No	The monitor status. Options: `ENABLED` (monitor is active and performing checks), `DISABLED` (monitor is inactive).
`monitor.apdexTarget`	Float	No	The monitor's Apdex target in seconds, used to populate SLA reports. Defaults to 7.0 seconds.

Sample request

mutation {
 syntheticsUpdateScriptApiMonitor(
 guid: ENTITY_GUID
 monitor: {
 locations: { public: ["LOCATION_1", "LOCATION_2"] }
 name: "YOUR_MONITOR_NAME"
 period: PERIOD
 runtime: {
 runtimeType: "RUNTIME_TYPE"
 runtimeTypeVersion: "RUNTIME_TYPE_VERSION"
 scriptLanguage: "SCRIPT_LANGUAGE"
 }
 script: "SCRIPT_CONTENT"
 status: STATUS
 apdexTarget: APDEX_TARGET
 }
 ) {
 errors {
 description
 type
 }
 }
}

Sample response

A successful response returns null for errors:

{
 "data": {
 "syntheticsUpdateScriptApiMonitor": {
 "errors": null
 }
 }
}

If there are any issues updating the monitor, the errors array will contain objects with description and type fields explaining what went wrong.

Upgrade a scripted API monitor's runtime

You can upgrade a scripted API monitor to use the newer Node.js 16.10 runtime. This ensures your monitor uses the latest Node.js features and security updates.

Input parameters

Parameter	Data Type	Is it Required?	Description
`guid`	String	Yes	The unique entity GUID of the monitor you want to upgrade.
`monitor.runtime.runtimeType`	String	Yes	The runtime type. `NODE_API` is the only accepted value.
`monitor.runtime.runtimeTypeVersion`	String	Yes	The runtime version. `16.10` is the only accepted value.
`monitor.runtime.scriptLanguage`	String	Yes	The scripting language. `JAVASCRIPT` is the only accepted value.

Sample request

mutation {
 syntheticsUpdateScriptApiMonitor(
 guid: "ENTITY_GUID"
 monitor: {
 runtime: {
 runtimeType: "NODE_API"
 runtimeTypeVersion: "16.10"
 scriptLanguage: "JAVASCRIPT"
 }
 }
 ) {
 errors {
 description
 type
 }
 }
}

Sample response

A successful response returns null for errors:

{
 "data": {
 "syntheticsUpdateScriptApiMonitor": {
 "errors": null
 }
 }
}

If there are any issues upgrading the monitor runtime, the errors array will contain objects with description and type fields explaining what went wrong.

Downgrade a scripted API monitor's runtime

You can downgrade a scripted API monitor to use a legacy runtime. This may be necessary for compatibility reasons, but note that legacy runtimes will be end-of-life on October 22, 2024.

Important

Legacy runtimes are deprecated and will be end-of-life on October 22, 2024. Downgrading to legacy runtimes is not recommended except for temporary compatibility needs.

Input parameters

Parameter	Data Type	Is it Required?	Description
`guid`	String	Yes	The unique entity GUID of the monitor you want to downgrade.
`monitor.runtime.runtimeType`	String	Yes	Set to empty string `""` to use legacy runtime.
`monitor.runtime.runtimeTypeVersion`	String	Yes	Set to empty string `""` to use legacy runtime.
`monitor.runtime.scriptLanguage`	String	Yes	Set to empty string `""` to use legacy runtime.

Sample request

mutation {
 syntheticsUpdateScriptApiMonitor(
 guid: "ENTITY_GUID"
 monitor: {
 runtime: { runtimeType: "", runtimeTypeVersion: "", scriptLanguage: "" }
 }
 ) {
 errors {
 description
 type
 }
 }
}

Sample response

A successful response returns null for errors:

{
 "data": {
 "syntheticsUpdateScriptApiMonitor": {
 "errors": null
 }
 }
}

If there are any issues downgrading the monitor runtime, the errors array will contain objects with description and type fields explaining what went wrong.

Move a scripted API monitor between VSE enabled private locations

You can move a scripted API monitor between VSE-enabled private locations. When moving monitors between private locations with verified script execution (VSE) enabled, you must include the script to regenerate HMACs for security validation.

Input parameters

Parameter	Data Type	Is it Required?	Description
`guid`	String	Yes	The unique entity GUID of the monitor you want to move.
`monitor.locations.private`	Array	Yes	Array of private location configurations. Each location requires a `guid` and `vsePassword` for VSE-enabled locations.
`monitor.locations.private.guid`	String	Yes	The entity GUID of the target private location.
`monitor.locations.private.vsePassword`	String	Yes	The VSE password for the target private location.
`monitor.script`	String	Yes	The JavaScript code that the monitor executes. This must be included to regenerate HMACs when moving between VSE-enabled locations.

Sample request

mutation {
 syntheticsUpdateScriptApiMonitor(
 guid: "ENTITY_GUID"
 monitor: {
 locations: {
 private: [{ guid: "LOCATION_GUID", vsePassword: "YOUR_VSE_PASSWORD" }]
 }
 script: "SCRIPT_CONTENT"
 }
 ) {
 errors {
 description
 type
 }
 monitor {
 status
 }
 }
}

Sample response

A successful response returns null for errors and includes the monitor status:

{
 "data": {
 "syntheticsUpdateScriptApiMonitor": {
 "errors": null,
 "monitor": {
 "status": "ENABLED"
 }
 }
 }
}

If there are any issues moving the monitor, the errors array will contain objects with description and type fields explaining what went wrong.

Delete a scripted API monitor

When a scripted API monitor is no longer needed, you can permanently remove it using the syntheticsDeleteMonitor mutation.

To delete a monitor, refer to the Delete Synthetic monitor section.

Create a scripted API monitor .css-21sua1{background:none;border:none;width:0;padding:0;}

Input parameters

Sample request

Sample response

Update a scripted API monitor

Input parameters

Sample request

Sample response

Upgrade a scripted API monitor's runtime

Input parameters

Sample request

Sample response

Downgrade a scripted API monitor's runtime

Important

Input parameters

Sample request

Sample response

Move a scripted API monitor between VSE enabled private locations

Input parameters

Sample request

Sample response

Delete a scripted API monitor

Create a scripted API monitor