Scan Engine API endpoints

reference brazil Updated Aug 25, 2026 6 min read api-endpoints.md
Raw file servicenow.com

Reference information for Scan Engine Headless API endpoints, authentication requirements, and response formats.

Base URL and versioning

Scan Engine API requests use this base URL:

Text
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

All API requests require these headers:

Header Value Required
Authorization Bearer <session_token_or_oauth_token> Yes
Content-Type application/json Yes, for write endpoints (POST)

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

Request limits and format requirements

All API request size limits and format requirements.

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

API endpoints

The Scan Engine API provides five endpoints for triggering scans, checking status, retrieving findings, and canceling scans.

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.

Scan modes and parameters

When triggering a scan via the /scan endpoint, use one of these modes in your request body:

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.

Error codes

This table lists all error codes returned by the Scan Engine API, their HTTP status, applicable endpoints, and troubleshooting guidance.

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.

Error handling strategies

When integrating the Scan Engine API into your automation, implement these strategies for common errors:

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.

Response formats

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

Success response

JSON
{  "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.

Error response

JSON
{  "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.

Findings response

Shell
{  "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.

For a complete list of fields returned in finding and resolved finding responses, see Scan Engine API field reference.

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

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.

Parent Topic:Scan Engine reference

Keywords APIendpointserror codesHTTP status
Search documentation
Search document titles and file paths on the brazil branch