--- title: Manage scripted API monitors source: https://docs.newrelic.com/docs/apis/nerdgraph/examples/synthetics-api/scripted-api-monitor --- New Relic allows you use NerdGraph to create [scripted API monitors](https://docs.newrelic.com/docs/synthetics/synthetic-monitoring/scripting-monitors/write-synthetic-api-tests). 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 [#create-scripted-api] 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](https://docs.newrelic.com/docs/accounts/accounts-billing/account-structure/account-id) where the monitor will be created. | | `monitor.locations.public` | Array | Yes | Array of [public location](https://docs.newrelic.com/docs/synthetics/synthetic-monitoring/using-monitors/add-edit-monitors/#setting-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 ```graphql 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: ```json { "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 [#update-scripted-api] 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](https://docs.newrelic.com/docs/apis/nerdgraph/examples/synthetics-api/query-synthetics-data#query-monitors) of the monitor you want to update. | | `monitor.locations.public` | Array | No | Array of [public location](https://docs.newrelic.com/docs/synthetics/synthetic-monitoring/using-monitors/add-edit-monitors/#setting-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 ```graphql 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: ```json { "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 [#upgrade-monitor-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](https://docs.newrelic.com/docs/apis/nerdgraph/examples/synthetics-api/query-synthetics-data#query-monitors) 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): ```graphql 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: ```json { "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 [#move-monitor] 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](https://docs.newrelic.com/docs/apis/nerdgraph/examples/synthetics-api/query-synthetics-data#query-monitors) 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 ```graphql 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: ```json { "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 [#delete-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](https://docs.newrelic.com/docs/apis/nerdgraph/examples/synthetics-api/ping-monitor/#delete-monitor) section. ## Query scripted API monitors [#query-scripted-api-monitors] Use NerdGraph to retrieve metadata, scripts, map IDs, or check the status of your scripted API monitors. For more information, refer to: - [Query all monitors](https://docs.newrelic.com/docs/apis/nerdgraph/examples/synthetics-api/query-synthetics-data#query-monitors): To list all synthetic monitors and their configurations. - [Map monitor ID to entity GUID](https://docs.newrelic.com/docs/apis/nerdgraph/examples/synthetics-api/query-synthetics-data#query-guid-mapping): To migrate legacy monitor IDs to entity GUIDs. - [Runtime upgrade status](https://docs.newrelic.com/docs/apis/nerdgraph/examples/synthetics-api/query-synthetics-data#query-runtime-upgrade-all): To check if your monitors are ready for the latest runtime upgrades. - [Query monitor script](https://docs.newrelic.com/docs/apis/nerdgraph/examples/synthetics-api/query-synthetics-data#query-monitor-script) - Retrieve JavaScript code from scripted monitors. To view complete list of query examples, refer to the [Query synthetics data](https://docs.newrelic.com/docs/apis/nerdgraph/examples/synthetics-api/query-synthetics-data) document.