---
sourceDocument: Xanadu API Reference
sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/xanadu/api-reference

 Release :

    - xanadu

ft:locale :

    - en-US

ft:publication_title :

    - Xanadu API Reference

ft:clusterId :

    - crapiref

bundleId :

    - crapiref

workflow :

    - Creator


---

# DiscoveryAPI - Scoped

# DiscoveryAPI - Scoped {#ariaid-title1}

* Release version: Xanadu
* 
* Updated August 1, 2024
* 
* ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 2 minutes to read

The DiscoveryAPI class provides methods that launch a quick discovery of a single IPv4 address and return summaries of previously launched discovery statuses for a single configuration item (CI) or for all
scanned CIs.

This class runs is in the `sn_discovery` namespace.

## DiscoveryAPI - discoverIpAddress(String ipAddress, String application, String source) {#ariaid-title2}

Discovers a specified IPv4 address.
A MID Server is selected automatically, based on the IP address provided or the application
specified.
{#r_DiscoAPIdiscoverIpAddress__table_c4m_wcd_qcb__entry__3}

| Name | Type | Description |
|-|-|-|
| application | String | Optional. Application configured for the MID Server. To define a source parameter but not an application parameter, use "NULL" as the place holder. Default: Discovery |
| ipAddress | String | IP address to discover. |
| source | String | Optional. Source of the Discovery. This same value appears in the optional Source field in the Discovery Status record, which indicates how the Discovery was triggered. Default: Discovery_API |
[Table 1. Parameters]

{#r_DiscoAPIdiscoverIpAddress__table_c4m_wcd_qcb} {#r_DiscoAPIdiscoverIpAddress__table_d4m_wcd_qcb__entry__2}

| Type | Description |
|-|-|
| String | Discovery status record sys_id. The following exceptions can be thrown during MID Server selection: * NoSuitableMidServerFoundException: `No appropriate MID Server available for this Discovery` * BadArgumentException: `Invalid argument detected during MID Server selection` {#r_DiscoAPIdiscoverIpAddress__ul_ms4_lqj_qcb} |
[Table 2. Returns]

{#r_DiscoAPIdiscoverIpAddress__table_d4m_wcd_qcb}  

    var sysid = sn_discovery.DiscoveryAPI.discoverIpAddress("11.23.125.39");

## DiscoveryAPI - reportCiIpAddressStatus(Object ipAddress, Object discoveryStatusSysId) {#ariaid-title3}

Used to return a summary of a configuration item's Discovery status given the specific status sys_id and IPv4 address.
The following exceptions can be thrown:

* DiscoveryStatusNotFoundException: `Displays this message: Discovery Status with sys id '<`invalid value`>' does not exist`
* DiscoveryDeviceHistoryNotFoundException: `Device History with Discovery Status sys id '<`invalid value`>' and ipAddress '<`invalid value`>' does not
  exist`
* IllegalArgumentException (invalid input arguments): This argument exception prevents input values from being null.
  * `Discovery Status sys id can not be null `
  * `ipAddress can not be null`
  {#r_DiscoAPIreportCiIpAddressStatus__ul_ul2_c4t_rcb}
* IllegalArgumentException (values stored in database): This argument exception prevents erroneous data from being returned to the caller in the case of bad attribute values.
  * `Discovery Status 'state' property can not be null`
  * `Device history 'source' property can not be null `
  * `Device history 'issues' property is not an integer: <`invalid value`>`
  * `Device history 'issues' property can not be less than 0: <`invalid value`>`
  {#r_DiscoAPIreportCiIpAddressStatus__ul_pjt_j4t_rcb}
{#r_DiscoAPIreportCiIpAddressStatus__ul_ztk_gft_rcb}
{#r_DiscoAPIreportCiIpAddressStatus__table_jlm_mts_rcb__entry__3}

| Name | Type | Description |
|-|-|-|
| ipAddress | string | The IPv4 address that was scanned. |
| discoveryStatusSysId | string | The sys_id of the Discovery status record for the IP address that was scanned. |
[Table 3. Parameters]

{#r_DiscoAPIreportCiIpAddressStatus__table_jlm_mts_rcb} {#r_DiscoAPIreportCiIpAddressStatus__table_klm_mts_rcb__entry__2}

| Type | Description |
|-|-|
| array | JavaScript array of immutable [ReportCiStatusOutputJS](https://servicenow-prod.fluidtopics.net/~m2~eMVZ8fRSrCqY5NcbVw#c_ReportCiStatusOutputJSScopedAPI "The ReportCiStatusOutputJS API provides methods that return specific object properties for the DiscoveryAPI reportCiIpAddressStatus method and then converts the information into a JSON string.") objects. |
[Table 4. Returns]

{#r_DiscoAPIreportCiIpAddressStatus__table_klm_mts_rcb}  

    var ipResultObj = sn_discovery.DiscoveryAPI.reportCiIpAddressStatus(ipAddress, discoveryStatus);

## DiscoveryAPI - reportCiStatus(Object discoveryStatusSysId) {#ariaid-title4}

Used to return a summary of a CI Discovery status given a specific Discovery Status
sys_id.
The following exceptions can be thrown:

* DiscoveryStatusNotFoundException: `Discovery Status with
  sys id '<`invalid value`>' does not exist `
* DiscoveryDeviceHistoryNotFoundException: `Device History
  with Discovery Status sys id '<`invalid value`>' and ipAddress
  '<`invalid value`>' does not exist`
* IllegalArgumentException (invalid input arguments): This argument exception prevents input values from being null.
  * `Discovery Status sys id can not be null`
  * `ipAddress can not be null`
  {#r_DiscoAPIreportCiStatus__ul_ul2_c4t_rcb}
* IllegalArgumentException (values stored in database): This argument exception imposes post conditions on database access values.
  * `Discovery Status 'state' property can not be null`
  * `Device history 'source' property can not be null`
  * `Device history 'issues' property is not an integer: <`invalid value`>`
  * `Device history 'issues' property can not be less than 0: <`invalid value`>`
  {#r_DiscoAPIreportCiStatus__ul_pjt_j4t_rcb}
{#r_DiscoAPIreportCiStatus__ul_ztk_gft_rcb}
{#r_DiscoAPIreportCiStatus__table_fzx_cwt_rcb__entry__3}

| Name | Type | Description |
|-|-|-|
| sys_id | string | The sys_id of a Discovery status record. |
[Table 5. Parameters]

{#r_DiscoAPIreportCiStatus__table_fzx_cwt_rcb} {#r_DiscoAPIreportCiStatus__table_gzx_cwt_rcb__entry__2}

| Type | Description |
|-|-|
| array | JavaScript array of immutable [ReportCiStatusOutputJS](https://servicenow-prod.fluidtopics.net/~m2~eMVZ8fRSrCqY5NcbVw#c_ReportCiStatusOutputJSScopedAPI "The ReportCiStatusOutputJS API provides methods that return specific object properties for the DiscoveryAPI reportCiIpAddressStatus method and then converts the information into a JSON string.") objects. |
[Table 6. Returns]

{#r_DiscoAPIreportCiStatus__table_gzx_cwt_rcb}  

    var ipResultObjArray = sn_discovery.DiscoveryAPI.reportCiStatus(discoveryStatus);
    for(var idx=0; idx < ipResultObjArray.length; idx++) {    
    var ipResultObj = ipResultObjArray[idx];