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


---

# Scan Engine API endpoints

# Scan Engine API endpoints {#ariaid-title1}

Release version: Brazil  
Updated August 25, 2026  
![](https://www.servicenow.com/docs/portal-asset/ico-clock) 6 minutes to read  
Reference information for Scan Engine Headless API endpoints, authentication requirements, and response formats.

## Base URL and versioning {#api-endpoints__section_base_url}

Scan Engine API requests use this base URL:

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

Always include `/v1/` in your requests---there is no default version.  
Important:  
Replace `<instance>` with your ServiceNow instance name.

## Authentication and required headers {#api-endpoints__section_authentication_headers}

All API requests require these headers:
{#api-endpoints__table_m1p_fg3_lkc__entry__3}

| Header | Value | Required |
|-|-|-|
| `Authorization` | `Bearer <session_token_or_oauth_token>` | Yes |
| `Content-Type` | `application/json` | Yes, for write endpoints (POST) |
[Table 1. Required headers]

{#api-endpoints__table_m1p_fg3_lkc}

All requests require the `sn_se.scan_engine_user` role. Requests without valid credentials return `401`.

## Request limits and format requirements {#api-endpoints__section_request_limits}

All API request size limits and format requirements.
{#api-endpoints__table_n1p_fg3_lkc__entry__2}

| Limit | Value |
|-|-|
| Maximum payload size | 64 KB per request |
| Date format | ISO 8601 (YYYY-MM-DDTHH:mm:ssZ) |
| Content-Type for write endpoints | `application/json` |
[Table 2. Request limits and format requirements]

{#api-endpoints__table_n1p_fg3_lkc}

## API endpoints {#api-endpoints__section_api_endpoints}

The Scan Engine API provides five endpoints for triggering scans, checking status, retrieving findings, and canceling scans.
{#api-endpoints__table_o1p_fg3_lkc__entry__3}

| Endpoint | Method | Purpose |
|-|-|-|
| `/scan` | POST | Trigger a new scan. Returns a `scan_result_sys_id` for tracking. |
| `/scan_status` | GET | Check the progress of a running scan. Pass `scan_result_sys_id` as a query parameter. |
| `/findings` | GET | Retrieve findings for a completed scan. Pass `scan_result_sys_id` as a query parameter. |
| `/resolved_findings` | GET | Retrieve findings that have been resolved or fixed over time. Supports filtering by date, definition, and scope. |
| `/cancel` | POST | Cancel a running scan. Pass `scan_number` or `scan_sys_id` in the request body. |
[Table 3. API endpoints]

{#api-endpoints__table_o1p_fg3_lkc}

## Scan modes and parameters {#api-endpoints__section_scan_modes}

When triggering a scan via the `/scan` endpoint, use one of these modes in your request body:
{#api-endpoints__table_scan_modes__entry__2}

| Mode | Description |
|-|-|
| `instance_scan` | Full or delta instance scan against all applicable definitions. Include `instance_scan_type` to specify full or delta. |
| `update_set` | Scans one or more update sets before promotion to production. Include `update_set_sys_ids` array with sys_ids (not update set numbers). |
| `application_scan` | Scans one or more applications with per-application concurrency. Include `application_sys_ids` array of sys_ids. |
| `content` | Scans raw ServiceNow XML records in-memory, without persisting them. Include `xml_content` with well-formed record_update XML. |
[Table 4. Scan modes]

{#api-endpoints__table_scan_modes}

## Error codes {#api-endpoints__section_error_codes}

This table lists all error codes returned by the Scan Engine API, their HTTP status, applicable endpoints, and troubleshooting guidance.
{#api-endpoints__table_p1p_fg3_lkc__entry__4}

| Error Code | HTTP Status | Applies to endpoints | Description |
|-|-|-|-|
| MISSING_REQUIRED_FIELD | 400 | All endpoints | A required field is missing from your request. Check the error message to identify which field is required. |
| INVALID_SCAN_MODE | 400 | POST /scan | The `scan_mode` value is not recognized. Verify it matches one of the supported modes: `instance_scan`, `update_set`, `application_scan`, or `content`. |
| INVALID_FIELD_VALUE | 400 | POST /scan, POST /cancel, GET /findings, GET /resolved_findings | A field value does not match the expected format or type. Check the error detail for which field needs correction. |
| INVALID_UPDATE_SET | 400 | POST /scan (update_set mode) | The supplied update set sys_id does not exist or is invalid. Verify the sys_id matches a valid update set record. |
| INVALID_XML_CONTENT | 400 | POST /scan (content mode) | The XML content is not well-formed or is missing the `<record_update>` root element. Validate the XML structure. |
| INVALID_APPLICATION | 400 | POST /scan (application_scan mode) | The supplied application sys_id does not exist or is invalid. Verify the sys_id matches a valid application record. |
| DEFINITION_NOT_FOUND | 400 | GET /findings | The scan definition specified in your query does not exist. Verify the definition sys_id or number. |
| PAYLOAD_TOO_LARGE | 413 | POST /scan, POST /cancel | Request body exceeds 64KB. Reduce the request size by using smaller batches or fewer records. |
| NOT_AUTHENTICATED | 401 | All endpoints | Your session token or OAuth credentials are invalid, expired, or missing. Re-authenticate and retry with valid credentials. |
| NOT_AUTHORIZED | 403 | All endpoints | Your user account does not have the `sn_se.scan_engine_user` role. Contact your administrator to request access. |
| SCAN_NOT_FOUND | 404 | GET /scan_status, GET /findings, GET /resolved_findings, POST /cancel | The scan result ID provided does not exist or has been purged. Verify the scan_result_sys_id or scan_number is correct. |
| APPLICATION_SCAN_NOT_FOUND | 404 | GET /findings | No findings exist for the specified application scan. The scan may not have completed or the application ID may be incorrect. |
| UPDATE_SET_SCAN_NOT_FOUND | 404 | GET /findings | No findings exist for the specified update set scan. The scan may not have completed or the update set ID may be incorrect. |
| INSTANCE_SCAN_NOT_FOUND | 404 | GET /findings | No findings exist for the specified instance scan. The scan may not have completed or the scan result may have been purged. |
| NO_ACTIVE_SCAN | 404 | POST /cancel | No active scan is running and no identifier was provided. Supply either `scan_sys_id` or `scan_number`, or verify a scan is currently active. |
| CONCURRENT_SCAN_RUNNING | 409 | POST /scan | Another scan is already running for this target. Wait at least 30 seconds and retry, or cancel the existing scan first. |
| ALREADY_CANCELLED | 409 | POST /cancel | The scan is already in a Cancelled state. No further cancellation is needed or possible. |
| SCAN_COMPLETE | 409 | POST /cancel | The scan has already completed and cannot be cancelled. Cancellation is only available for in-progress or queued scans. |
[Table 5. Scan Engine API error codes]

{#api-endpoints__table_p1p_fg3_lkc}

## Error handling strategies {#api-endpoints__section_error_handling_strategies}

When integrating the Scan Engine API into your automation, implement these strategies for common errors:
{#api-endpoints__table_error_handling_strategies__entry__2}

| Error Type | Strategy |
|-|-|
| Rate limiting (409 CONCURRENT_SCAN_RUNNING) | Implement exponential back off. Start with a 30-second wait, then increase on subsequent retries. |
| Authentication (401 NOT_AUTHENTICATED) | Refresh your credentials and retry immediately. Log the error for audit purposes. |
| Authorization (403 NOT_AUTHORIZED) | This is a configuration issue. Contact your administrator to grant the required role. don't retry automatically. |
| Server errors (500) | Implement exponential backoff with a maximum retry count. Log the error and alert your operations team if retries are exhausted. |
| Validation errors (400) | These indicate a problem with your request. Review the error message and correct the field or value before retrying. |
[Table 6. Error handling strategies]

{#api-endpoints__table_error_handling_strategies}

## Response formats {#api-endpoints__section_response_formats}

The API uses consistent response structures. All successful responses include a `result` object. All error responses include an `error` object.  
Success response

    {
      "result": {
        "scan_result_sys_id": "a1b2c3d4e5f6g7h8",
        "status": "Complete",
        "total_errors": 5,
        "total_warnings": 12,
        "se_score": 72
      }
    }

The `result` object contains:

* `scan_result_sys_id`: Unique identifier for this scan. Use it to check status and retrieve findings.
* `status`: Current scan state---`Waiting`, `Getting Ready`, `Complete`, or other terminal states.
* `total_errors`: Count of violations classified as errors.
* `total_warnings`: Count of violations classified as warnings.
* `se_score`: Overall health score on a 0--100 scale.
{#api-endpoints__ul_r1p_fg3_lkc}  
Error response

    {
      "error": {
        "code": "MISSING_REQUIRED_FIELD",
        "message": "A required field is missing",
        "detail": {
          "fields": ["scan_mode", "source"]
        }
      },
      "status": "failure"
    }

The `error` object contains:

* `code`: Machine-readable error code. Use this for programmatic error handling.
* `message`: Human-readable description of the error.
* `detail`: Additional context such as which fields are missing.
{#api-endpoints__ul_s1p_fg3_lkc}  
Findings response

    {
      "result": {
        "findings": [
          {
            "severity": "error",
            "message": "Missing mandatory field",
            "affected_record": "cmdb_ci_00001"
          }
        ],
        "definitions": [ ... ],
        "pagination": {
          "limit": 100,
          "offset": 0,
          "has_more": false,
          "total": 17
        }
      }
    }

The findings response includes:

* `findings[]`: Array of violations found during the scan. Each finding includes severity, message, and affected_record.
* `definitions[]`: Deduplicated rule metadata for all findings in the response.
* `pagination`: Offset-based pagination info. Default 100 results per page, max 1,000.

{#api-endpoints__ul_t1p_fg3_lkc}

For a complete list of fields returned in finding and resolved finding responses, see [Scan Engine API field reference](https://www.servicenow.com/docs/cixtE6FmZ4q9Ow6l5mxHmQ "Field reference for scan status, findings, and resolved findings API responses.").

## Common query parameters {#api-endpoints__section_query_parameters}

These query parameters are used across multiple Scan Engine API endpoints to identify scans, paginate results, and filter findings by definition or resolution date.
{#api-endpoints__table_u1p_fg3_lkc__entry__3}

| Parameter | Used in | Description |
|-|-|-|
| `scan_result_sys_id` | `/scan_status`, `/findings`, `/resolved_findings` | The unique identifier returned when you triggered the scan. Required for status and current findings queries. |
| `offset` | `/findings`, `/resolved_findings` | Number of results to skip before returning results. Used for pagination. Defaults to 0. |
| `limit` | `/findings`, `/resolved_findings` | Number of results to return per page. Defaults to 100, maximum 1,000. |
| `definition` | `/resolved_findings` | Filter by definition sys_id or number. Optional. |
| `resolved_on_from` | `/resolved_findings` | Filter findings resolved on or after this date. Use ISO 8601 format YYYY-MM-DD. Optional. |
| `resolved_on_to` | `/resolved_findings` | Filter findings resolved on or before this date. Use ISO 8601 format YYYY-MM-DD. Optional. |
[Table 7. Common query parameters table]

{#api-endpoints__table_u1p_fg3_lkc}