---
sourceDocument: Brazil Impact
sourceDocumentLink: https://www.servicenow.com/docs/r/impact

 Release :

    - brazil

ft:locale :

    - en-US

ft:publication_title :

    - Brazil Impact

ft:clusterId :

    - ipact

bundleId :

    - ipact


---

# Trigger a scan via API

# Trigger a scan via API {#ariaid-title1}

Release version: Brazil  
Updated September 23, 2026  
![](https://www.servicenow.com/docs/portal-asset/ico-clock) 4 minutes to read  
You can start a Scan Engine scan by sending a POST request to the scan endpoint. The API returns a unique scan result ID that you use to check progress and retrieve findings.

## Before you begin

Role required: sn_se.scan_engine_user

## About this task

## Procedure

1. Set up your authentication credentials.  
   Prepare your session token or OAuth bearer token. You will include this in the `Authorization` header of your request. See [Configure the OAuth authentication method development instance](https://www.servicenow.com/docs/JMYCW35QMol3B5RjYlAheQ "Set up OAuth authentication for instance-to-instance Scan Engine integrations using several stages, an integration user account, an OAuth2 configuration record, and provider and client application registries.") for details.
2. Determine the scan mode for your use case.  
   Choose the type of scan to run. The Scan Engine API supports four scan modes:
   {#trigger-scan-api__entry__2}

   | Scan mode | Description |
   |-|-|
   | `instance` | Full or delta instance scan against all applicable definitions. |
   | `update_set` | Scans one or more update sets before promotion to production. |
   | `application` | Scans one or more applications with per-application concurrency. |
   | `content` | Scans raw ServiceNow XML records in-memory, without persisting them. |
   [Table 1. Scan modes]

   Note:  
   Each mode also accepts a suffixed spelling, such as `instance_scan`, `update_set_scan`, `application_scan`, and `content_scan`. These remain permanently supported for backward compatibility. The response always echoes the canonical unsuffixed mode name.
3. Compose your POST request to the scan endpoint.  
   Send your request to:

       POST https://<instance>.service-now.com/api/sn_se/v1/scan_operations/scan

   Replace `<instance>` with your ServiceNow instance name. Always include `/v1/` in the URL---there is no default version.
4. Add required headers and the request body.  
   Include these headers:
   * `Authorization: Bearer <your_token>`
   * `Content-Type: application/json`

   Send a JSON body matching your chosen scan mode.

   **Instance scan (delta or full)**

       {
         "scan_mode": "instance",
         "trigger_channel": "api",
         "instance_scan_type": "delta"
       }

   {#trigger-scan-api__entry__13}

   | Field | Default | Description |
   |-|-|-|
   | `instance_scan_type` | `delta` | Type of instance scan to run. Allowed values: `full` or `delta`. |
   [Table 2. Instance scan fields]

   **Update set scan**

       {
         "scan_mode": "update_set",
         "trigger_channel": "api",
         "update_set_sys_ids": ["<32-char sys_id>", "..."]
       }

   {#trigger-scan-api__entry__19}

   | Field | Default | Description |
   |-|-|-|
   | `update_set_sys_ids` | Required | Array of sys_ids to scan (not update set numbers). Must be a JSON array --- sending a single sys_id as a bare string is rejected with 400 INVALID_FIELD_VALUE. |
   [Table 3. Update set scan fields]

   Optional fields for update set scans:
   {#trigger-scan-api__entry__25}

   | Field | Default | Description |
   |-|-|-|
   | `remote` | `false` | Scans a `sys_remote_update_set` instead of a local update set. |
   | `is_batch` | `false` | By default, child and nested update sets are scanned along with the ones you specify. Set to `true` to scan only the exact update sets listed. |
   [Table 4. Optional update set scan fields]

   **Application scan**

       {
         "scan_mode": "application",
         "trigger_channel": "api",
         "application_sys_ids": ["<32-char sys_id>", "..."]
       }

   {#trigger-scan-api__entry__34}

   | Field | Default | Description |
   |-|-|-|
   | `application_sys_ids` | Required | Array of application sys_ids to scan. The API natively supports multiple applications in one request. Must be a JSON array --- sending a single sys_id as a bare string is rejected with 400 INVALID_FIELD_VALUE. |
   [Table 5. Application scan fields]

   **Content scan (XML payload)**

       {
         "scan_mode": "content",
         "trigger_channel": "api",
         "xml_content": "<record_update table=\"sys_script_include\">...</record_update>"
       }

   {#trigger-scan-api__entry__40}

   | Field | Default | Description |
   |-|-|-|
   | `xml_content` | Required | A single well-formed `<record_update>` XML document. |
   | `trigger_channel` | `api` | Recommended field for new integrations. The `source` field continues to work, but `trigger_channel` is the name to standardize on. If you send both fields with conflicting values, the API returns 400 INVALID_FIELD_VALUE. |
   [Table 6. Content scan fields]

   Warning:  
   The maximum payload size is 64KB per request.
5. Send the request and capture the scan result ID.  
   On success, the API returns a response with a `scan_result_sys_id`:

       {
         "result": {
           "scan_result_sys_id": "45ec57e5ffc743109124ffffffffffda",
           "status": "Getting Ready",
           "scan_mode": "instance"
         }
       }

   {#trigger-scan-api__entry__49}

   | Scan mode | HTTP status | Description |
   |-|-|-|
   | `instance`, `update_set`, `application` | 202 Accepted | The scan is queued and not run synchronously. Poll `scan_status` for the result. |
   | `content` | 200 OK | The scan runs in-memory and returns the result directly. |
   [Table 7. HTTP status codes by scan mode]

   Save the `scan_result_sys_id` to check scan status and retrieve findings later.
6. Handle any errors.  
   If the request fails, the API returns an error code and details. Common errors:
   {#trigger-scan-api__entry__57}

   | Error code | What it means |
   |-|-|
   | MISSING_REQUIRED_FIELD (400) | A required field is missing from your request. |
   | INVALID_SCAN_MODE (400) | The `scan_mode` value is not recognized. |
   | NOT_AUTHORIZED (403) | Your user account is missing the `sn_se.scan_engine_user` role. |
   | CONCURRENT_SCAN_RUNNING (409) | Another scan is already running for this target. |
   | NO_ELIGIBLE_DEFINITIONS (409) | A content scan found no scan definitions on the instance applicable to the submitted XML. Distinguishes nothing could run from a clean scan that found nothing. |
   | PAYLOAD_TOO_LARGE (413) | Request body exceeds 64KB. Reduce the request size. |
   [Table 8. Common trigger errors]

   See [Scan Engine API error codes](https://www.servicenow.com/docs/1lpgNvMrX_ooupbEGYqKwg "Error codes returned by the Scan Engine API, organized by HTTP status code. Each section includes proposed solutions and handling strategies.") for the full error code reference.
7. **Optional:** Cancel a scan if it is no longer needed.  
   If a scan is running, but no longer needed, you can cancel it. Send a POST request to the cancel endpoint:

       POST https://<instance>.service-now.com/api/sn_se/v1/scan_operations/cancel

   **Request body:**

       {
         "scan_sys_id": "45ec57e5ffc743109124ffffffffffda"
       }

   Provide either `scan_sys_id` (the sys_id of the scan result) or `scan_number` (the scan result number). Both are optional; if neither is supplied, the API targets the most recently created scan in
   an active state.
   {#trigger-scan-api__entry__71}

   | Outcome | HTTP status and meaning |
   |-|-|
   | immediate | HTTP 200 --- The scan was in getting_ready or no batch was running. Cancelled synchronously. Status is now Cancelled. |
   | graceful | HTTP 202 --- A batch was actively running. Cancel requested. The scan will finalize to Cancelled once the batch completes. |
   | no_action | HTTP 200 --- The scan completed naturally between the request and applying it. No cancellation needed. |
   | event_queue | HTTP 200 --- No active scan, but a pending queued scan event was found and voided. |
   [Table 9. Cancel response outcomes]

   Tip:  
   Graceful cancellation waits for the current batch to complete before stopping. If you need to cancel immediately, issue the request while the scan is still in getting_ready state.

## Result

A scan is now running on your target. The API returned a scan result ID that you can use to track progress. Proceed to check scan status and retrieve findings once the scan completes. You can cancel the scan at any time if it is no
longer needed.

## What to do next

After triggering a scan, monitor its progress by polling the status endpoint. See [Check scan status and retrieve findings](https://www.servicenow.com/docs/AYN9GBZcWSZTntp8iv1ZRA "After triggering a scan, poll the status endpoint to monitor progress and retrieve findings when the scan completes.") for details.