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. Use `22.20.0` for the current Node.js version (recommended). Older specific versions like `16.10` are also accepted but will be deprecated.
`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. Use `22.20.0` for the current Node.js version (recommended). Older specific versions like `16.10` are also accepted but will be deprecated.
`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 runtime. We recommend using version 22.20.0 for the most recent Node.js release.

Important

Node.js version management: Specific Node.js versions (such as 16.10) will reach end-of-life. On Nov 18, 2026, scripted API monitors still on older Node.js versions will be force upgraded to Node.js 22. The current supported version is 22.20.0. To ensure your monitors use the latest Node.js updates and features, upgrade to runtimeTypeVersion: "22.20.0" before this date.

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. Use `22.20.0` for the most recent Node.js version (recommended). Older specific versions like `16.10` are also accepted but will be deprecated.
`monitor.runtime.scriptLanguage`	String	Yes	The scripting language. `JAVASCRIPT` is the only accepted value.

Sample request

Upgrade to Node.js version 22.20.0 (recommended):

mutation {
  syntheticsUpdateScriptApiMonitor(
    guid: "ENTITY_GUID"
    monitor: {
      runtime: {
        runtimeType: "NODE_API"
        runtimeTypeVersion: "22.20.0"
        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.

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

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