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.
Tip
Quick Navigation: Use the links below to jump to specific query types:
- General monitor queries: Query all monitors or specific types
- Monitor-specific queries: Retrieve the script from a scripted monitor, or the ordered steps from a step monitor
- Supporting entity queries: Query private locations, secure credentials, and monitor downtimes
- Advanced queries: Map legacy monitor IDs and check runtime upgrade status
To learn additional query capabilities available to your synthetic entities, check out NerdGraph entities API tutorial.
General monitor queries
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
Parameter | Data Type | Is it Required? | Description |
|---|---|---|---|
| String | Yes | The search query to filter entities. Use |
Sample query
{ actor { entitySearch(query: "domain = 'SYNTH' AND type = 'MONITOR'") { results { entities { ... on SyntheticMonitorEntityOutline { guid name accountId monitorType tags { key values } } } } } }}Entity support queries
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
Parameter | Data Type | Is it Required? | Description |
|---|---|---|---|
| String | Yes | The search query to filter entities. Use |
Sample query
{ actor { entitySearch(query: "domain = 'SYNTH' AND type = 'PRIVATE_LOCATION'") { results { entities { accountId guid name tags { key values } } } } }}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
Parameter | Data Type | Is it Required? | Description |
|---|---|---|---|
| String | Yes | The search query to filter entities. Use |
Sample query
{ actor { entitySearch(query: "domain = 'SYNTH' AND type = 'MONITOR_DOWNTIME'") { results { entities { accountId guid name tags { key values } } } } }}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
Parameter | Data Type | Is it Required? | Description |
|---|---|---|---|
| String | Yes | The search query to filter entities. Use |
Sample query
{ actor { entitySearch(query: "domain = 'SYNTH' AND type = 'SECURE_CRED'") { results { entities { ... on SecureCredentialEntityOutline { accountId guid name tags { key values } updatedAt } } } } }}Monitor-specific queries
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
Parameter | Data Type | Is it Required? | Description |
|---|---|---|---|
| Integer | Yes | The New Relic account ID that contains the monitor. |
| String | Yes | The unique entity GUID of the scripted monitor whose script you want to retrieve. |
Sample query
{ actor { account(id: ACCOUNT_ID) { synthetics { script(monitorGuid: "ENTITY_GUID") { text } } } }}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
Parameter | Data Type | Is it Required? | Description |
|---|---|---|---|
| Integer | Yes | The New Relic account ID that contains the monitor. |
| String | Yes | The unique entity GUID of the step monitor whose steps you want to retrieve. |
Sample query
{ actor { account(id: ACCOUNT_ID) { synthetics { steps(monitorGuid: "ENTITY_GUID") { ordinal type values } } } }}Advanced queries
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
Parameter | Data Type | Is it Required? | Description |
|---|---|---|---|
| String | Yes | The search query to find the monitor. Use |
Sample query
{ actor { entitySearch(query: "(domainId = 'MONITOR_ID')") { results { entities { ... on SyntheticMonitorEntityOutline { guid name monitorId } } } } }}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
Parameter | Data Type | Is it Required? | Description |
|---|---|---|---|
| String | Yes | The search query to filter entities. Use |
Sample query
{ actor { entitySearch(query: "domain = 'SYNTH' AND type = 'RUNTIME_VALIDATION'") { results { entities { accountId guid name tags { key values } } } } }}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
Parameter | Data Type | Is it Required? | Description |
|---|---|---|---|
| String | Yes | The search query to filter entities. Use |
Sample query
{ actor { entitySearch( query: "domain = 'SYNTH' AND type = 'RUNTIME_VALIDATION' AND domainId = 'MONITOR_ID'" ) { results { entities { accountId guid name tags { key values } } } } }}