Query synthetic monitoring data

After setting up your monitoring infrastructure, you can use queries to retrieve information about your synthetic entities. Queries make requests to fetch data about monitors, private locations, credentials, and downtimes. This tutorial provides examples of how to use the NerdGraph API to query synthetic monitoring data.

To learn additional query capabilities available to your synthetic entities, check out NerdGraph entities API tutorial.

Query monitors

This query retrieves all synthetic monitors in your account, returning essential information including the monitor's GUID, name, account ID, monitor type, and associated tags. The tags contain additional configuration details and metadata about each monitor.

Input parameters

Sample query

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

Query private locations

This query retrieves all private locations in your account, returning essential information including the location's GUID, name, account ID, and associated tags. Private locations allow you to monitor applications behind your firewall, and their configuration details are accessible through the tags.

Input parameters

Sample query

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

Query monitor downtimes

This query retrieves all monitor downtimes in your account, returning essential information including the downtime's GUID, name, account ID, and associated tags. Monitor downtimes are scheduled periods when synthetic monitors stop running, useful during planned maintenance or known outages. Configuration details such as schedule type, timezone, and recurrence patterns are stored in tags.

Input parameters

Sample query

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

Query secure credentials

This query retrieves all secure credentials in your account, returning metadata information including the credential's GUID, name, account ID, tags, and last update timestamp. Secure credentials help store, protect, and centrally manage sensitive information like passwords, API keys, or encoded certificates. For security reasons, querying secure credentials returns metadata only, but not the actual credential values themselves.

Input parameters

Sample query

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

Query monitor script

This query retrieves the script content used in a scripted API or scripted browser monitor. The script contains the JavaScript code that defines the monitor's behavior, such as API calls, browser interactions, or custom validation logic. This query only works with scripted monitor types - other monitor types (simple, ping, step, certificate check, broken links) will return an error since they don't use custom scripts.

Input parameters

Sample query

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

Query monitor steps

This query retrieves the steps configured for a step monitor. Step monitors provide codeless, multi-step browser-based monitoring through a sequence of predefined actions like navigation, clicks, form inputs, and assertions. Each step has an ordinal position, a type that defines the action, and values that contain the step's configuration data. This query only works with step monitors - other monitor types will return an error since they don't use step-based configurations.

Input parameters

Sample query

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

Query to map monitor ID to entity GUID

This query retrieves the entity GUID for a synthetic monitor using the monitor ID. This is useful when you have the legacy numeric monitor ID and need to convert it to the entity GUID format required for most NerdGraph operations. The entity GUID is the modern identifier used for updates, deletions, and other monitor management tasks, while the monitor ID is the older numeric identifier that may appear in URLs or legacy integrations.

Input parameters

Sample query

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

Query runtime upgrade status (all monitors)

This query retrieves the status of all runtime upgrade tests for legacy runtime monitors in your account. These tests validate whether monitors using older runtimes (like Chrome 72 or Node.js API legacy) can successfully run on newer runtimes (Chrome 100+ or Node.js 16.10). The results populate the runtime upgrades UI and help you identify which monitors are ready for upgrade. The test result is stored in the validationStatus tag, and if the upgrade test failed, detailed error information is available in the validationError tag.

Input parameters

Sample query

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

Query runtime upgrade status (specific monitor)

This query retrieves the status of a runtime upgrade test for a specific legacy runtime monitor using the monitor ID. This is useful when you want to check the upgrade readiness of a particular monitor rather than all monitors in your account. The test validates whether the monitor can successfully run on newer runtimes and these results populate the runtime upgrades UI. The test result is stored in the validationStatus tag, and if the upgrade test failed, detailed error information is available in the validationError tag.

Input parameters

Sample query

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