NerdGraph tutorial: Manage your synthetic monitors

Our NerdGraph API allows you to automate creating, updating, or deleting your synthetic monitors, private locations, secure credentials, and monitor downtimes.

Requirements

Requirements include:

General NerdGraph requirements
Relevant user permissions: the same synthetic monitoring permissions that apply for using the synthetics UI apply for using NerdGraph

Understand fields in NerdGraph explorer

You can view field definitions in NerdGraph explorer, but it may help to better understand the LOCATION, PERIOD, TAGS, and other fields.

To identify a private location in your scripts, use the private location's entity GUID. If the private location is configured to use verified script execution, also include the vsePassword attribute. For example:

locations: {
  private: {
    guid: LOCATION_ENTITY_GUID, 
    vsePassword: YOUR_VSE_PASSWORD
  }
}

Public locations use the location identifier without the AWS_ prefix, for example:

locations: {
  public: ["US_EAST_2", "US_WEST_1"]
}

The PERIOD attribute defines a time interval for your monitors to execute. To define the interval, use these forms:

EVERY_MINUTE for every minute.
EVERY_N_MINUTES, where 'N' is minutes. Supported values include EVERY_5_MINUTES, EVERY_10_MINUTES, EVERY_15_MINUTES, and EVERY_30_MINUTES.
EVERY_HOUR for every hour.
EVERY_N_HOURS, where 'N' is hours. Supported values include EVERY_6_HOURS and EVERY_12_HOURS.
EVERY_DAY for once a day.

Some fields are for more advanced configurations. These are optional.

For ping monitors, these include:

HEADER_NAME: Your custom header names that appear on the request.
HEADER_VALUE: The custom header value on the request.
REDIRECT_IS_FAILURE: Your monitor reports a failure if it's redirected.
VALIDATION_TEXT: If this text is not included in your monitor's response, it returns a failure.
TLS_VALIDATION: Verifies the validity of the SSL certificate chain.
BYPASS_HEAD_REQUEST: Bypasses the initial HEAD request and instead makes a GET request.

For simple browser monitors:

RUNTIME_TYPE: The runtime type used by your monitor. "CHROME_BROWSER" is the only accepted value.
RUNTIME_TYPE_VERSION: The runtime type version used by your monitor. "100" is the only accepted value.
SCRIPT_LANGUAGE: The language used in your monitor. "JAVASCRIPT" is the only accepted value.

For scripted API monitors:

SCRIPT_CONTENT: The actual contents of the script. This should not be based64 encoded.
RUNTIME_TYPE: The runtime type used by your monitor. "NODE_API" is the only accepted value.
RUNTIME_TYPE_VERSION: The runtime type version used by your monitor. The only accepted value is 16.10.
SCRIPT_LANGUAGE: The language used in your monitor. "JAVASCRIPT" is the only accepted value.

For scripted browser monitors:

SCRIPT_CONTENT: The actual contents of the script. This should not be based64 encoded.
RUNTIME_TYPE: The runtime type used by your monitor. "CHROME_BROWSER" is the only accepted value.
RUNTIME_TYPE_VERSION: The runtime type version used by your monitor. "100" is the only accepted value.
SCRIPT_LANGUAGE: The language used in your monitor. "JAVASCRIPT" is the only accepted value.

For step monitors:

RUNTIME_TYPE: The runtime type used by your monitor. "CHROME_BROWSER" is the only accepted value.
RUNTIME_TYPE_VERSION: The runtime type version used by your monitor. "100" is the only accepted value.
SCRIPT_LANGUAGE: The language used in your monitor. "JAVASCRIPT" is the only accepted value.

For certificate check monitors:

DAYS_UNTIL_EXPIRATION: Notifies you when you need to update your certificate. For example, if you wanted a notification 30 days before the certificate expires, you would input 30.
RUNTIME_TYPE: The runtime type used by your monitor. "NODE_API" is the only accepted value.
RUNTIME_TYPE_VERSION: The runtime type version used by your monitor. The only accepted value is 16.10.
SCRIPT_LANGUAGE: The language used in your monitor. "JAVASCRIPT" is the only accepted value.

For broken link monitors:

RUNTIME_TYPE: The runtime type used by your monitor. "NODE_API" is the only accepted value.
RUNTIME_TYPE_VERSION: The runtime type version used by your monitor. The only accepted value is 16.10.
SCRIPT_LANGUAGE: The language used in your monitor. "JAVASCRIPT" is the only accepted value.

For all monitors:

APDEX_TARGET: The monitor's Apdex target used to populate SLA reports. Defaults to 7 seconds (7000ms).

Use queries to retrieve data

Queries make requests to fetch data. To learn additional query capabilities available to your synthetic entities, check out NerdGraph entities API tutorial.

You can query your synthetic monitors to get current status information about your data or details about the monitor configuration. Many monitor configurations are surfaced as tags.

{
  actor {
    entitySearch(query: "domain = 'SYNTH' AND type = 'MONITOR'") {
      results {
        entities {
          ... on SyntheticMonitorEntityOutline {
            guid
            name
            accountId
            monitorType
            tags {
              key
              values
            }
          }
        }
      }
    }
  }
}

You're able to query your private locations:

{
  actor {
    entitySearch(query: "domain = 'SYNTH' AND type = 'PRIVATE_LOCATION'") {
      results {
        entities {
          accountId
          guid
          name
          tags {
            key
            values
          }
        }
      }
    }
  }
}

Query existing monitor downtimes. Configuration details are stored in tags.

{
  actor {
    entitySearch(query: "domain = 'SYNTH' AND type = 'MONITOR_DOWNTIME'") {
      results {
        entities {
          accountId
          guid
          name
          tags {
            key
            values
          }
        }
      }
    }
  }
}

Querying secure credentials lets you retrieve metadata only, but not the credential values themselves:

{
  actor {
    entitySearch(query: "domain = 'SYNTH' AND type = 'SECURE_CRED'") {
      results {
        entities {
          ... on SecureCredentialEntityOutline {
            accountId
            guid
            name
            tags {
              key
              values
            }
            updatedAt
          }
        }
      }
    }
  }
}

Retrieve the script used in a scripted API or scripted browser monitor. Other monitor types will return an error.

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      synthetics {
        script(monitorGuid: "ENTITY_GUID") {
          text
        }
      }
    }
  }
}

Retrieve the steps configured for a step monitor. Other monitor types will return an error.

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      synthetics {
        steps(monitorGuid: "ENTITY_GUID") {
          ordinal
          type
          values
        }
      }
    }
  }
}

Retrieve the entity GUID for a synthetic monitor using the monitor ID.

{
  actor {
    entitySearch(
      query: "(domainId = 'MONITOR_ID')"
    ) {
      results {
        entities {
          ... on SyntheticMonitorEntityOutline {
            guid
            name
            monitorId
          }
        }
      }
    }
  }
}

Retrieve the status of all runtime upgrade tests for legacy runtime monitors. These tests populate the runtime upgrades UI. The test result is stored in the validationStatus tag. If the upgrade test failed, the error message is available in the validationError tag.

{
  actor {
    entitySearch(query: "domain = 'SYNTH' AND type = 'RUNTIME_VALIDATION'") {
      results {
        entities {
          accountId
          guid
          name
          tags {
            key
            values
          }
        }
      }
    }
  }
}

Retrieve the status of a runtime upgrade test for a single legacy runtime monitor. These test results populate the runtime upgrades UI. The test result is stored in the validationStatus tag. If the upgrade test failed, the error message is available in the validationError tag.

{
  actor {
    entitySearch(query: "domain = 'SYNTH' AND type = 'RUNTIME_VALIDATION' and domainId = 'MONITOR_ID'") {
      results {
        entities {
          accountId
          guid
          name
          tags {
            key
            values
          }
        }
      }
    }
  }
}

Create your synthetic monitors

Below are some sample requests to automate the creation of your synthetic monitors.

Tip

Include the runtime object that includes runtimeType, runtimeTypeVersion, and scriptLanguage to use a newer runtime. Do not include the runtime object and these attributes to continue using a legacy runtime.

Important

As of August 26, 2024, you can no longer create new monitors using legacy runtimes on public or private locations. On October 22, 2024, we will end of life the containerized private minion (CPM) and legacy synthetics runtime versions.

For public locations, use the runtime upgrade UI to update your monitors to the newest runtimes.
For private locations, please review our recommended migration steps to avoid monitor degradation.

Ping monitors check that your application is running. Here's an example for creating one in NerdGraph:

mutation {
    syntheticsCreateSimpleMonitor (
      accountId: YOUR_ACCOUNT_ID 
      monitor: {
        locations: {
          public: ["LOCATION_1", "LOCATION_2"]
          }, 
        name: "YOUR_MONITOR_NAME", 
        period: PERIOD, 
        status: STATUS, 
        uri: "MONITORED_URI", 
        advancedOptions: {
          customHeaders: {
            name: "HEADER_NAME", 
            value: "HEADER_VALUE"
          }, 
          redirectIsFailure: REDIRECT_IS_FAILURE, 
          responseValidationText: "VALIDATION_TEXT", 
          shouldBypassHeadRequest: BYPASS_HEAD_REQUEST, 
          useTlsValidation: TLS_VALIDATION
        }, 
        apdexTarget: APDEX_TARGET
      }
  ) {
      errors {
        description
        type
      }
    }
  }

Simple browser monitors use Chrome instances to mimic customer visits. Here's an example for creating one in NerdGraph:

mutation {
    syntheticsCreateSimpleBrowserMonitor (
      accountId: YOUR_ACCOUNT_ID, 
      monitor: {
        browsers: [BROWSERS],
        devices: [DEVICES], 
        locations: {
          public: ["LOCATION_1", "LOCATION_2"]
          }, 
        name: "YOUR_MONITOR_NAME", 
        period: PERIOD, 
        runtime: {
          runtimeType: "RUNTIME_TYPE",
          runtimeTypeVersion: "RUNTIME_TYPE_VERSION",
          scriptLanguage: "SCRIPT_LANGUAGE"
        }
        status: STATUS, 
        uri: "MONITORED_URI", 
        advancedOptions: {
          customHeaders: {
            name: "HEADER_NAME", 
            value: "HEADER_VALUE"
          }, 
          enableScreenshotOnFailureAndScript: ENABLE_SCREENSHOT, 
          responseValidationText: "VALIDATION_TEXT", 
          useTlsValidation: TLS_VALIDATION
        }, 
        apdexTarget: APDEX_TARGET
      ) {
      errors {
        description
        type
      }
    }
  }

Scripted browser monitors are more complex interactions with your pages and applications. Here's an example for creating one in NerdGraph:

mutation {
    syntheticsCreateScriptBrowserMonitor (
      accountId: YOUR_ACCOUNT_ID, 
      monitor: { 
        browsers: [BROWSERS],
        devices: [DEVICES], 
        locations: {
          public: ["LOCATION_1", "LOCATION_2"]
          }, 
        name: "MONITOR_NAME", 
        period: PERIOD,
        runtime: {
          runtimeType: "RUNTIME_TYPE",
          runtimeTypeVersion: "RUNTIME_TYPE_VERSION",
          scriptLanguage: "SCRIPT_LANGUAGE"
        }
        script: "SCRIPT_CONTENT", 
        status: STATUS, 
        advancedOptions: {
          enableScreenshotOnFailureAndScript: ENABLE_SCREENSHOT
        }, 
        apdexTarget: APDEX_TARGET
      }
    ) {
      errors {
        description
        type
      }
    }
  }

Scripted API monitors check your API endpoints. Here's an example for creating one in NerdGraph:

mutation {
    syntheticsCreateScriptApiMonitor (
      accountId: YOUR_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
      }
    }
  }

Step monitors provide codeless multi-step browser based monitors. Here's an example for creating one in NerdGraph:

mutation {
syntheticsCreateStepMonitor (
  accountId: NR_ACCOUNT_ID, 
  monitor: {
    browsers: [BROWSERS],
    devices: [DEVICES], 
    locations: {
      public: ["LOCATION_1", "LOCATION_2"]
      },  
    name: "MONITOR_NAME", 
    period: PERIOD, 
    runtime: {
      runtimeType: "RUNTIME_TYPE",
      runtimeTypeVersion: "RUNTIME_TYPE_VERSION",
      scriptLanguage: "SCRIPT_LANGUAGE"
      }
    status: STATUS, 
    steps: [{
      ordinal: 0, 
      type: NAVIGATE, 
      values: ["MONITORED_URI"],["USER_AGENT"]
      },{
      ordinal: STEP_NUMBER,
      type: STEP_TYPE,
      values: ["CONDITIONAL_TYPE","VALUE"]
    }]
    advancedOptions: {
      enableScreenshotOnFailureAndScript: ENABLE_SCREENSHOT
    }, 
    apdexTarget: APDEX_TARGET
  }
) {
    errors {
      description
      type
    }
}
}

Set up monitors to notify you when your SSL certificates are about to expire. Here's an example for creating one in NerdGraph:

mutation {
    syntheticsCreateCertCheckMonitor (
      accountId: YOUR_ACCOUNT_ID, 
      monitor: {
        domain: "DOMAIN", 
        locations: {
          public: ["LOCATION_1", "LOCATION_2"]
          },
        name: "YOUR_MONITOR_NAME", 
        numberDaysToFailBeforeCertExpires: DAYS_UNTIL_EXPIRATION, 
        period: PERIOD, 
        status: STATUS, 
        apdexTarget: APDEX_TARGET
      }
    ) {
      errors {
        description
        type
      }
    }
  }

Broken links monitors check the links on a webpage for failure. Here's an example for creating one in NerdGraph:

mutation {
  syntheticsCreateBrokenLinksMonitor (
    accountId: YOUR_ACCOUNT_ID, 
    monitor: {
      locations: {
        public: ["LOCATION_1", "LOCATION_2"]
        }, 
      name: "YOUR_MONITOR_NAME", 
      period: PERIOD, 
      status: STATUS, 
      apdexTarget: APDEX_TARGET, 
      uri: "MONITOR_URI", 
      tags: {
        key: "YOUR_TAG_NAME", 
        values: "TAG_VALUE"
        }
      }
    ) {
      errors {
        description
        type
      }
  }
}

Update your synthetic monitors

While you can't change the monitor type after creating it, you can update its settings. Only the guid and the settings that need updated are required as part of the request.

Tip

Include the runtime object that includes runtimeType, runtimeTypeVersion, and scriptLanguage to upgrade a monitor to use a newer runtime. Include this object and set these attributes to empty string to downgrade to a legacy runtime. Do not include this object and these attributes to continue using a legacy runtime.

Use this to update your ping monitors:

mutation {
  syntheticsUpdateSimpleMonitor (
    guid: "ENTITY_GUID", 
    monitor: {
      locations: {
        public: ["LOCATION_1", "LOCATION_2"]
      },  
      name: "YOUR_MONITOR_NAME", 
      period: PERIOD, 
      status: STATUS, 
      uri: "MONITORED_URI", 
      advancedOptions: {
        customHeaders: {
          name: "HEADER_NAME", 
          value: "HEADER_VALUE"
        }, 
        redirectIsFailure: REDIRECT_IS_FAILURE, 
        responseValidationText: "VALIDATION_TEXT", 
        shouldBypassHeadRequest: BYPASS_HEAD_REQUEST, 
        useTlsValidation: TLS_VALIDATION
      }, 
      apdexTarget: APDEX_TARGET
    }
  ) {
    errors {
      description
      type
    }
  }
}

To update a simple browser monitor (including the ability to upgrade the runtime version), use this:

mutation {
    syntheticsUpdateSimpleBrowserMonitor (
      guid: ENTITY_GUID, 
      monitor: {
        browsers: [BROWSERS],
        devices: [DEVICES], 
        locations: {
          public: ["LOCATION_1", "LOCATION_2"]
          }, 
        name: "YOUR_MONITOR_NAME", 
        period: PERIOD, 
        runtime: {
          runtimeType: "RUNTIME_TYPE",
          runtimeTypeVersion: "RUNTIME_TYPE_VERSION",
          scriptLanguage: "SCRIPT_LANGUAGE"
        }
        status: STATUS, 
        uri: "MONITORED_URI", 
        advancedOptions: {
          customHeaders: {
            name: "HEADER_NAME", 
            value: "HEADER_VALUE"
          }, 
          enableScreenshotOnFailureAndScript: ENABLE_SCREENSHOT, 
          responseValidationText: "VALIDATION_TEXT", 
          useTlsValidation: TLS_VALIDATION
        }, 
        apdexTarget: APDEX_TARGET
      ) {
      errors {
        description
        type
      }
    }
  }

To update a scripted browser monitor (including the ability to upgrade the runtime version), use this:

mutation {
    syntheticsUpdateScriptBrowserMonitor (
      guid: ENTITY_GUID, 
      monitor: { 
        browsers: [BROWSERS],
        devices: [DEVICES], 
        locations: {
          public: ["LOCATION_1", "LOCATION_2"]
          }, 
        name: "MONITOR_NAME", 
        period: PERIOD,
        runtime: {
          runtimeType: "RUNTIME_TYPE",
          runtimeTypeVersion: "RUNTIME_TYPE_VERSION",
          scriptLanguage: "SCRIPT_LANGUAGE"
        }
        script: "SCRIPT_CONTENT", 
        status: STATUS, 
        advancedOptions: {
          enableScreenshotOnFailureAndScript: ENABLE_SCREENSHOT
        }, 
        apdexTarget: APDEX_TARGET
      }
    ) {
      errors {
        description
        type
      }
    }
  }

To update a scripted API monitor (including the ability to upgrade the runtime version), use this:

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
      }
    }
  }

Use this to update a step monitor:

mutation {
  syntheticsUpdateStepMonitor (
    guid: ENTITY_GUID, 
    monitor: {
      browsers: [BROWSERS],
      devices: [DEVICES], 
      locations: {
        public: ["LOCATION_1", "LOCATION_2"]
        },  
      name: "MONITOR_NAME", 
      period: PERIOD, 
      runtime: {
        runtimeType: "RUNTIME_TYPE",
        runtimeTypeVersion: "RUNTIME_TYPE_VERSION",
        scriptLanguage: "SCRIPT_LANGUAGE"
        }
      status: STATUS, 
      steps: [{
        ordinal: 0, 
        type: NAVIGATE, 
        values: ["MONITORED_URI"],["USER_AGENT"]
        },{
        ordinal: STEP_NUMBER,
        type: STEP_TYPE,
        values: ["VALUE_1","VALUE_2"]
      }]
      advancedOptions: {
        enableScreenshotOnFailureAndScript: ENABLE_SCREENSHOT
      }, 
      apdexTarget: APDEX_TARGET
    }
  ) {
      errors {
        description
        type
      }
  }
}

Use this to update a certificate check monitor:

mutation {
    syntheticsUpdateCertCheckMonitor (
      guid: ENTITY_GUID, 
      monitor: {
        domain: "DOMAIN", 
        locations: {
          public: ["LOCATION_1", "LOCATION_2"]
          },
        name: "YOUR_MONITOR_NAME", 
        numberDaysToFailBeforeCertExpires: DAYS_UNTIL_EXPIRATION, 
        period: PERIOD, 
        status: STATUS, 
        apdexTarget: APDEX_TARGET
      }
    ) {
      errors {
        description
        type
      }
    }
  }

Use this to update a broken links monitor:

mutation {
  syntheticsUpdateBrokenLinksMonitor (
    guid: ENTITY_GUID, 
    monitor: {
      locations: {
        public: ["LOCATION_1", "LOCATION_2"]
        }, 
      name: "YOUR_MONITOR_NAME", 
      period: PERIOD, 
      status: STATUS, 
      apdexTarget: APDEX_TARGET, 
      uri: "MONITOR_URI", 
      tags: {
        key: "YOUR_TAG_NAME", 
        values: "TAG_VALUE"
        }
      }
    ) {
      errors {
        description
        type
      }
  }
}

You can use the below example to update a simple browser, scripted API, or scripted browser monitor to the new Chrome 100+ or Node.js 16.10 runtimes. The following example upgrades a scripted browser monitor to the new runtime from the legacy runtime.

To update a simple browser monitor using the below example, change the mutation to syntheticsUpdateSimpleBrowserMonitor instead of syntheticsUpdateScriptBrowserMonitor.

To update a scripted API monitor using the below example, change the mutation to syntheticsUpdateScriptApiMonitor instead of syntheticsUpdateScriptBrowserMonitor.

Check out optional-fields for additional details on runtime settings.

mutation {
  syntheticsUpdateScriptBrowserMonitor ( 
    guid: "<ENTITY_GUID>", 
    monitor: {
      runtime: {
        runtimeType: "RUNTIME_TYPE", 
        runtimeTypeVersion: "RUNTIME_TYPE_VERSION", 
        scriptLanguage: "SCRIPT_LANGUAGE"
        }
      }
    ) {
    errors {
      description
      type
    }
  }
}

You can use the below example to update a simple browser, scripted API, or scripted browser monitor to use a legacy runtime prior to the October 22, 2024 EOL. The following example downgrades a scripted browser monitor to the legacy runtime from the new runtime.

To update a simple browser monitor using the below example, change the mutation to syntheticsUpdateSimpleBrowserMonitor instead of syntheticsUpdateScriptBrowserMonitor.

To update a scripted API monitor using the below example, change the mutation to syntheticsUpdateScriptApiMonitor instead of syntheticsUpdateScriptBrowserMonitor.

Check out optional-fields for additional details on runtime settings.

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

Delete a synthetic monitor

Use these scripts to delete your monitors:

Manage your private locations

A private location allows you to monitor applications behind your firewall. When you create a private location, you install and configure private minions to execute the monitors assigned to that private location.

mutation{
  syntheticsCreatePrivateLocation (
    accountId: NR_ACCOUNT_ID,
    name: "PrivateLocationName",
    description: "Optional description",
    verifiedScriptExecution: false
  ) {
    guid
    errors {
      description
      type
    }
  }
}

mutation {
  syntheticsUpdatePrivateLocation (
    guid: YOUR_ENTITY_GUID,     
    description: "EnterYourDescription", 
    verifiedScriptExecution: true
  ) {
  description
  verifiedScriptExecution
  errors {
    description
    type
    }
  }
}

Manage your secure credentials

You use secure credentials when storing, protecting, and centrally managing protected information used by your monitors, like passwords, API keys, or encoded certificates. Using NerdGraph allows you to programmatically change the values of your secure credentials if you need to reset any credentials for any reason.

mutation {
  syntheticsCreateSecureCredential (
    accountId: YOUR_ENTITY_GUID, 
    description: "YourOptionalDescription", 
    key: SECURE_CREDENTIAL_NAME, 
    value: SECURE_CREDENTIAL_VALUE 
    ) {
    errors {
      description
    }
  }
}

mutation {
  syntheticsUpdateSecureCredential (
    accountId: YOUR_ACCOUNT_ID, 
    description: "YourOptionalDescription", 
    key: SECURE_CREDENTIAL_NAME, 
    value: SECURE_CREDENTIAL_VALUE) {
    createdAt
    lastUpdate
    errors {
      description
    }
  }
}

Manage your monitor downtimes

Monitor downtimes let you specify times that your synthetics should stop running. We've provided different snippets that demonstrate how to schedule monitor downtimes for your synthetics. You need to update these snippets to specify timezone, start times, and end times. To learn more about when you might schedule monitor downtimes, check out our doc Disable monitoring during scheduled maintenance times. To find timezone values, see the tz database of time zones. For example, America/Los Angeles would use the PDT abbreviation.

mutation {
  syntheticsCreateOnceMonitorDowntime (
    accountId: NR_ACCOUNT_ID,
    name: "MonitorDowntimeName",
    monitorGuids: ["OptionalMonitorEntityGuid", "OptionalMonitorEntityGuid"],
    timezone: "Timezone",
    startTime: "yyyy-MM-ddTHH:mm:ss",
    endTime: "yyyy-MM-ddTHH:mm:ss"
  ) {
    guid,
    accountId,
    name,
    monitorGuids,
    timezone,
    startTime,
    endTime
  }
}

mutation {
  syntheticsCreateDailyMonitorDowntime (
    accountId: NR_ACCOUNT_ID,
    name: "MonitorDowntimeName",
    monitorGuids: ["OptionalMonitorEntityGuid", "AnotherOptionalMonitorEntityGuid"],
    timezone: "Timezone",
    startTime: "yyyy-MM-ddTHH:mm:ss",
    endTime: "yyyy-MM-ddTHH:mm:ss",
    endRepeat: {
      onDate: "yyyy-MM-ddTHH:mm:ss",
      onRepeat: Int
    }
  ) {
    guid,
    accountId,
    name,
    monitorGuids,
    timezone,
    startTime,
    endTime,
    endRepeat {
      onDate,
      onRepeat
    }
  }
}

mutation {
  syntheticsCreateWeeklyMonitorDowntime (
    accountId: NR_ACCOUNT_ID,
    name: "MonitorDowntimeName",
    monitorGuids: ["OptionalMonitorEntityGuid", "AnotherOptionalMonitorEntityGuid"],
    timezone: "Timezone",
    startTime: "yyyy-MM-ddTHH:mm:ss",
    endTime: "yyyy-MM-ddTHH:mm:ss",
    endRepeat: {
      onDate: "yyyy-MM-ddTHH:mm:ss",
      onRepeat: Int
    },
    maintenanceDays: [WeekDaysEnums]
  ) {
    guid,
    accountId,
    name,
    monitorGuids,
    timezone,
    startTime,
    endTime,
    endRepeat {
      onDate,
      onRepeat
    },
    maintenanceDays
  }
}

mutation {
  syntheticsCreateMonthlyMonitorDowntime (
    accountId: NR_ACCOUNT_ID,
    name: "MonitorDowntimeName",
    monitorGuids: ["OptionalMonitorEntityGuid", "AnotherOptionalMonitorEntityGuid"],
    timezone: "Timezone",
    startTime: "yyyy-MM-ddTHH:mm:ss",
    endTime: "yyyy-MM-ddTHH:mm:ss",
    endRepeat: {
      onDate: "yyyy-MM-ddTHH:mm:ss",
      onRepeat: Int
    },
    frequency: {
      daysOfWeek: {
        weekDay: WeekDaysEnum,
        ordinalDayOfMonth: DayOfMonthOrdinal
      },
      daysOfMonth: [Int]
    }
  ) {
    guid,
    accountId,
    name,
    monitorGuids,
    timezone,
    startTime,
    endTime,
    endRepeat {
      onDate,
      onRepeat
    },
    frequency {
      daysOfWeek {
        weekDay,
        ordinalDayOfMonth
      },
      daysOfMonth
    }
  }
}

mutation {
  syntheticsEditMonitorDowntime (
    guid: "MonitorDowntimeEntityGuid",
    name: "MONITOR_DOWNTIME_NAME",
    monitorGuids: ["OptionalMonitorEntityGuid", "AnotherOptionalMonitorEntityGuid"],
    once: {
      timezone: "Timezone",
      startTime: "yyyy-MM-ddTHH:mm:ss",
      endTime: "yyyy-MM-ddTHH:mm:ss"
    },
    daily: {
      timezone: "Timezone",
      startTime: "yyyy-MM-ddTHH:mm:ss",
      endTime: "yyyy-MM-ddTHH:mm:ss",
      endRepeat: {
        onDate: "yyyy-MM-ddTHH:mm:ss",
        onRepeat: Int
      }
    },
    weekly: {
      timezone: "Timezone",
      startTime: "yyyy-MM-ddTHH:mm:ss",
      endTime: "yyyy-MM-ddTHH:mm:ss",
      endRepeat: {
        onDate: "yyyy-MM-ddTHH:mm:ss",
        onRepeat: Int
      },
      maintenanceDays: [WeekDaysEnums]
    },
    monthly: {
      timezone: "Timezone",
      startTime: "yyyy-MM-ddTHH:mm:ss",
      endTime: "yyyy-MM-ddTHH:mm:ss",
      endRepeat: {
        onDate: "yyyy-MM-ddTHH:mm:ss",
        onRepeat: Int
      },
      frequency: {
        daysOfWeek: {
          weekDay: WeekDaysEnum,
          ordinalDayOfMonth: DayOfMonthOrdinal
      },
      daysOfMonth: [Int]
    }
  ) {
    guid,
    accountId,
    name,
    monitorGuids,
    timezone,
    startTime,
    endTime,
    endRepeat {
      onDate,
      onRepeat
    },
    maintenanceDays,
    frequency {
      daysOfWeek {
        weekDay,
        ordinalDayOfMonth
      },
      daysOfMonth
    }
  }
}

NerdGraph tutorial: Manage your synthetic monitors

Requirements .css-21sua1{background:none;border:none;width:0;padding:0;}

Understand fields in NerdGraph explorer

Define devices fields

Define location fields

Define period fields

Define tags fields

Define optional fields

Use queries to retrieve data

Query monitors

Query private locations

Query monitor downtimes

Query secure credentials

Query monitor script

Query monitor steps

Query to map monitor ID to entity GUID

Query to retrieve the status of all runtime upgrade tests

Query to retrieve the status of a runtime upgrade test by monitor ID

Create your synthetic monitors

Tip

Important

Create a ping monitor

Create a simple browser monitor

Create a scripted browser

Create a scripted API monitor

Create a step monitor

Create a certificate check monitor

Create a broken links monitor

Update your synthetic monitors

Tip

Update a ping monitor

Update a simple browser monitor

Update a scripted browser monitor

Update an API test monitor

Update a step monitor

Update a certificate check monitor

Update a broken links monitor

Upgrade a monitor's runtime

Downgrade a monitor's runtime

Delete a synthetic monitor

Delete monitor

Manage your private locations

Create a private location

Update a private location

Delete a private location

Purge a private location job queue

Manage your secure credentials

Create a secure credential

Update a secure credential

Delete a secure credential

Manage your monitor downtimes

Create a monitor downtime that runs once

Create a monitor downtime that runs daily

Create a monitor downtime that runs weekly

Create a monitor downtime that runs monthly

Update a monitor downtime

Delete a monitor downtime

Requirements