SyntheticsAsyncBulkCreate API

concept australia Updated Sep 10, 2026 14 min read synth-async-api.md
Raw file servicenow.com

The SyntheticsAsyncBulkCreate API provides endpoints to manage asynchronous synthetic monitor creation.

Use this API to create up to 5,000 monitors per request. Monitors can be created using data in JSON or CSV format. For more information about using JSON or CSV files with Postman or Terminal, see the Synthetic Monitoring Developer Guide.

This API requires the Synthetic monitoring application (com.snc.uib.sow_synthetics), which is available on the ServiceNow Store. Before calling this API, at least one MID Server location must be configured for synthetic monitoring. For instructions, see Create synthetic monitoring locations.

Parent Topic:REST API reference

SyntheticsAsyncBulkCreate - GET /sn_sow_synthetics/synthetics_async_bulk_create/{job_id}

Checks the progress of a bulk monitor creation job.

To call this endpoint, the user must have the x_snc_sow_synthetics.synthetics_viewer role.

URL format

Versioned URL: /api/sn_sow_synthetics/{api_version}/synthetics_async_bulk_create/{job_id}

Default URL: /api/sn_sow_synthetics/synthetics_async_bulk_create/{job_id}

Supported request parameters

Name

Description

api_version

Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest. Data type: String

job_id

ID of the monitor creation job.Table: Synthetics Bulk Job [sn_sow_synthetics_bulk_job]

Column: Job ID

Data type: String
|Name|Description| |----|-----------| |None| |
Name Description
None

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Header

Description

Accept

Data format of the response body. Only supports application/json.

Authorization

HTTP basic authentication or OAuth bearer token.Basic authentication format:

Text
Authorization: Basic <base64-encoded-username:password>

OAuth format:

Text
Authorization: Bearer <access-token>
|Header|Description| |------|-----------| |None| |

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

Status code Description
202 Accepted. Job status successfully retrieved.
401 Unauthorized. The user credentials are incorrect or have not been passed.
403 Forbidden. The user must have the x_snc_sow_synthetics.synthetics_viewer role to check job status.
404 Not found. A job with the provided ID was not found in table Synthetics Bulk Job [sn_sow_synthetics_bulk_job].
500 Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

Response body parameters (JSON)

Name

Description

error

Object returned if the API request failed.Data type: Object

CSS
"error": {   "code": "String",   "details": {Object},   "message": "String"}

error.code

Error code. Possible values:

  • AUTHENTICATION_FAILED
  • AUTHORIZATION_FAILED
  • JOB_NOT_FOUND
  • INTERNAL_ERROR

Data type: String

error.details

Additional details about the error. The elements included in this object vary based on the type of error.

Data type: Object

error.message

Error message.Data type: String

result

Object containing information about the status of the monitor creation job.Data type: Object

JavaScript
"result": {   "errors": [Array],   "job_id": "String",   "message": "String",   "status": "String",   "summary": {Object}}

result.job_id

ID of the monitor creation job.Table: Synthetics Bulk Job [sn_sow_synthetics_bulk_job]

Column: Job ID

Data type: String

result.message

Message about the status of the monitor creation job.Data type: String

result.status

Status of the monitor creation job.Possible values:

  • pending
  • processing
  • completed
  • failed

Data type: String

result.summary

Current summary data for the monitor creation job.Data type: Object

JavaScript
"summary": {   "created": Number,   "failed": Number,   "processed": Number,   "successful": Number,   "total": Number,   "updated": Number}

result.summary.created

Number of monitors successfully created.Data type: Number

result.summary.failed

Number of monitors that couldn't be created or updated.Data type: Number

result.summary.processed

Number of monitors processed by the job.Data type: Number

result.summary.successful

Number of monitors successfully created or updated.Data type: Number

result.summary.total

Total number of monitors included in the job.Data type: Number

result.summary.updated

Number of monitors successfully updated.Data type: Number

result.errors

Error information for failed monitors.Data type: Array

JavaScript
"errors": [   {      "check_number": Number,      "error_code": "String",      "error_message": "String",      "name": "String"         }]

result.errors.check_number

Order of the monitor in the checks array provided in the request body for POST /sn_sow_synthetics/synthetics_async_bulk_create.Data type: Number

result.errors.error_code

Error code.Possible values:

  • CREATE_FAILED
  • UPDATE_FAILED

Data type: String

result.errors.error_message

Error message.Data type: String

result.errors.name

Name of the monitor.Data type: String
### cURL request

This example checks the status of a monitor creation job.

Shell
curl "https://instance.service-now.com/api/sn_sow_synthetics/v1/synthetics_async_bulk_create/BCJ-1776889518281-0baf339f" \--request GET \--header "Accept:application/json" \--user 'username':'password'

Response body - job processing.

JSON
{   "result": {      "job_id": "BCJ-1776889518281-0baf339f",      "status": "processing",      "message": "Processing in progress: 150/500 (30%)",      "summary": {         "total": 500,         "processed": 150,         "successful": 148,         "created": 145,         "updated": 3,         "failed": 2      }   }}

Response body - job successfully completed.

JSON
{   "result": {      "job_id": "BCJ-1776889518281-0baf339f",      "status": "completed",      "message": "Job completed successfully. 497 monitors created, 3 updated, 0 failed out of 500 total.",      "summary": {         "total": 500,         "processed": 500,         "successful": 500,         "created": 497,         "updated": 3,         "failed": 0      }   }}

Response body - job completed with errors.

JSON
{   "result": {      "job_id": "BCJ-1776889518281-0baf339f",      "status": "completed",      "message": "Job completed. 98 monitors created, 0 updated, 2 failed out of 100 total.",      "summary": {         "total": 100,         "processed": 100,         "successful": 98,         "created": 98,         "updated": 0,         "failed": 2      },      "errors": [         {            "check_number": 23,            "name": "Invalid Monitor",            "error_code": "CREATE_FAILED",            "error_message": "cmdb_ci is required"         },         {            "check_number": 45,            "name": "Bad Location Monitor",            "error_code": "CREATE_FAILED",            "error_message": "Location not found: invalid_sys_id"         }      ]   }}

SyntheticsAsyncBulkCreate - POST /sn_sow_synthetics/synthetics_async_bulk_create

Creates multiple synthetic monitors in a single asynchronous operation.

This endpoint supports creating up to 5,000 monitors per request, with a maximum payload size of 10MB. Calling this endpoint submits a job to asynchronously create the monitors in batches of 500. Check the job status by calling the endpoint GET /sn_sow_synthetics/v1/synthetics_async_bulk_create/{job_id}.

Uploaded data is checked for uniqueness against existing monitors on the fields name, url, location, valid_http_code, and valid_http_code_type to avoid creating duplicates.

To call this endpoint, the user must have the x_snc_sow_synthetics.synthetics_editor role.

URL format

Versioned URL: /api/sn_sow_synthetics/{api_version}/synthetics_async_bulk_create

Default URL: /api/sn_sow_synthetics/synthetics_async_bulk_create

Supported request parameters

Name

Description

api_version

Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest. Data type: String
|Name|Description| |----|-----------| |None| |

Name

Description

checks

Required. Array of endpoint configuration objects to create monitors for. This array can contain a maximum of 5,000 objects per API request.Data type: Array

JavaScript
"checks": [   {      "alert_severity": Number,      "alert_tags": {Object},      "body": "String",      "body_condition": {Object},      "cmdb_ci": "String",      "credential": "String",      "description": "String",      "enabled": Boolean,      "headers": [Array],      "interval": Number,      "locations": [Array],      "max_latency_ms": Number,      "method": "String",      "name": "String",      "parent_service_sys_id": "String",      "query_string": "String",      "should_create_alert": Boolean,      "single_api_check_sys_id": "String",      "support_group_sys_id": "String",      "valid_http_code": "String",      "valid_http_code_type": "String"   }]

checks.alert_severity

Severity level of alerts created for failed monitor tests. Only use this parameter if checks.should_create_alert is set to true.Valid values:

  • 1: Critical
  • 2: Major
  • 3: Minor
  • 4: Warning
  • 5: OK

Default: 1

Data type: Number

checks.alert_tags

Custom tags to use for alerts created for failed monitor tests. Only use this parameter if checks.should_create_alert is set to true.The elements contained in this object vary based on the tags used. For example, tags could be used for the environment or team as shown below.

JavaScript
//Example custom tags"alert_tags": {   "environment": "production",        "team": "platform"     }

Default: Empty object

Data type: Object

checks.body

Request body for POST, PUT, or PATCH endpoints. Must be a valid JSON or XML string depending on the Content-Type header. Maximum size is 10KB.Default: Null

Data type: String

checks.body_condition

Response body validation.Data type: Object

Text
"body_condition": {        "expression": "String",   "type": "String"     }

checks.body_condition.expression

Expression to check the response body against. The expression can be any string value, including support for regex, JSONPath, and XPath.Default: Null

Data type: String

checks.body_condition.type

Type of validation used to evaluate the response body against checks.body_condition.expression.Valid values (case-sensitive):

  • equals: Exact match.
  • not_equals: Not equal to.
  • contains: Contains substring.
  • not_contains: Does not contain substring.
  • regex: Regular expression match.
  • jsonpath: JSONPath expression match.
  • xpath: XPath expression match. Used for XML responses.

Default: Null

Data type: String

checks.cmdb_ci

Required. Sys_id of the CMDB endpoint configuration item (CI) or endpoint URL.If a URL is provided that matches an existing endpoint CI, that CI is used for the monitor. If a URL is provided that doesn't match an existing endpoint CI, a CI is created and used for the monitor.

Table: HTTP Endpoint [cmdb_ci_endpoint_http]

Data type: String

checks.credential

Sys_id of the credential for the monitor to include in the endpoint request.Table: Credentials [discovery_credentials]

Default: Null

Data type: String

checks.description

Description of the monitor.Data type: String

checks.enabled

Flag that indicates whether the monitor will start executing immediately after creation.Valid values:

  • true: The monitor starts executing immediately after creation.
  • false: The monitor won't start executing until it is enabled.

Default: true

Data type: Boolean

checks.headers

Array of HTTP headers for the monitor to include in the endpoint request.Data type: Array

Default: Empty array (no headers)

Text
"headers": [   {      "name": "String",      "value": "String"   }]

checks.headers.name

Name of the HTTP header, such as Authorization or Content-Type.Data type: String

checks.headers.value

Value of the HTTP header, such as Bearer token or application/json.Data type: String

checks.interval

Required. Frequency of monitor execution in minutes.ServiceNow hosted locations are limited to 6 tests per minute per monitor.

Valid values: 1-60

For example, a value of 5 sets the monitor to execute once every five minutes.

Data type: Number

checks.locations

Required. List of sys_ids of MID Server locations to use for the monitor.Table: Synthetic Location [sn_sow_synthetics_location]

Data type: String

checks.max_latency_ms

Maximum acceptable response time in milliseconds. The general guideline is 500-5000ms depending on the endpoint type. The monitor checks against this value when testing, and the test fails if the response time exceeds this value.

Default: Null (no latency threshold)

Data type: Number

checks.method

Required. HTTP method to use. Valid values (case-insensitive):

  • DELETE
  • GET
  • HEAD
  • PATCH
  • POST
  • PUT

Data type: String

checks.name

Required. Display name for the monitor.Maximum length: 100 characters

Data type: String

checks.parent_service_sys_id

Required unless the endpoint has a parent service relationship in the CI Relationship [cmdb_rel_ci] table. Sys_id of the business service this endpoint supports. Used for service-level reporting and impact analysis.Table: Business Service [cmdb_ci_service]

Data type: String

checks.query_string

Query parameters for the monitor to include in the endpoint request.Default: Null

Data type: String

checks.should_create_alert

Flag that indicates whether the monitor will create an alert if a test fails.Valid values:

  • true: Alerts are created if monitor tests fail.
  • false: Alerts aren't created if monitor tests fail.

Default: false

Data type: Boolean

checks.single_api_check_sys_id

Sys_id of the monitor for the endpoint. Use this parameter to update an existing monitor.Table: Single API [sn_sow_synthetics_check_single_api]

Default: Null

Data type: String

checks.support_group_sys_id

Required unless the endpoint has a parent service relationship in the CI Relationship [cmdb_rel_ci] table. Sys_id of the support group responsible for this endpoint. Used for alert routing and assignment.Table: Group [sys_user_group]

Data type: String

checks.valid_http_code

Required. Expected HTTP status codes for a successful response. Valid formats:

  • Single value, such as 200.
  • Range of values, such as 200-202.
  • Comma-separated list of values, such as '200,201,204'.
  • Regular expression, such as 2[0-9]{2} (matches codes 200-299).

The monitor checks against these values when testing, and the test fails if the actual status code doesn't match an expected value.

Default: Null

Data type: String

checks.valid_http_code_type

Required. Type of validation used to check the HTTP status code from a response.Valid values (case-sensitive):

  • equals: Checks for an exact match with checks.valid_http_code.
  • in_range: Checks that the status code is within the range of values provided in checks.valid_http_code.
  • regex: Checks for a match with the regular expression provided in checks.valid_http_code.

Default: Null

Data type: String
### Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Header

Description

Accept

Data format of the response body. Only supports application/json.

Authorization

HTTP basic authentication or OAuth bearer token.Basic authentication format:

Text
Authorization: Basic <base64-encoded-username:password>

OAuth format:

Text
Authorization: Bearer <access-token>

Content-Type

Data format of the request body. Supported types: application/json or text/csv. Default: application/json
|Header|Description| |------|-----------| |None| |

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

Status code

Description

202

Accepted. A bulk monitor creation job was submitted.

400

Bad request. Request validation failed. Check error.code and error.message in the response body for error details.Common causes:

  • Malformed JSON or CSV payload.
  • Required field not provided.
  • Field value out of range or not valid.
  • Referenced endpoint CI not found in table HTTP Endpoint [cmdb_ci_endpoint_http].
  • Referenced MID Server location not found in table Synthetic Location [sn_sow_synthetics_location].
  • Referenced service not found in table Business Service [cmdb_ci_service].
  • Duplicate monitor. A monitor already exists for the endpoint.

401

Unauthorized. The user credentials are incorrect or have not been passed.

403

Forbidden. The user must have the x_snc_sow_synthetics.synthetics_editor role to create monitors.

413

Payload too large. Request body exceeds 10MB limit.

415

Unsupported media type. The payload must be formatted as JSON or CSV.

429

Too many requests or too many active monitor creation jobs. Wait and retry. Check error.code and error.message in the response body for more information.Rate limits:

  • 10 requests per minute
  • 100 requests per hour
  • 1000 requests per day

500

Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.
### Response body parameters \(JSON\)

Name

Description

error

Object returned if the API request failed.Data type: Object

CSS
"error": {   "code": "String",   "details": {Object},   "message": "String"}

error.code

Error code. Possible values:

  • INVALID_JSON_FORMAT
  • INVALID_CSV_FORMAT
  • MISSING_REQUIRED_FIELD
  • INVALID_FIELD_VALUE
  • CMDB_CI_NOT_FOUND
  • LOCATION_NOT_FOUND
  • SERVICE_NOT_FOUND
  • DUPLICATE_MONITOR
  • PAYLOAD_TOO_LARGE
  • UNSUPPORTED_MEDIA_TYPE
  • RATE_LIMIT_EXCEEDED
  • CONCURRENT_JOB_LIMIT
  • AUTHENTICATION_FAILED
  • AUTHORIZATION_FAILED
  • JOB_NOT_FOUND
  • INTERNAL_ERROR

Data type: String

error.details

Additional details about the error. The elements included in this object vary based on the type of error.

Data type: Object

error.message

Error message.Data type: String

result

Object containing information about the monitor creation job.Data type: Object

JSON
"result": {   "job_id": "String",   "job_sys_id": "String",   "message": "String",   "status": "String",   "status_check_url": "String"}

result.job_id

ID of the monitor creation job.Table: Synthetics Bulk Job [sn_sow_synthetics_bulk_job]

Column: Job ID

Data type: String

result.job_sys_id

Sys_id of the monitor creation job.Table: Synthetics Bulk Job [sn_sow_synthetics_bulk_job]

Data type: String

result.message

Message about the status of the monitor creation job.Data type: String

result.status

Status of the monitor creation job.For a successful API request (status code 202 Accepted), the value of this parameter is pending.

Data type: String

result.status_check_url

Endpoint for tracking the current status of the monitor creation job. For more information, see GET /sn_sow_synthetics/v1/synthetics_async_bulk_create/{job_id}.Data type: String
### cURL request

This example submits a job to create monitors for two API endpoints.

Shell
curl "https://instance.service-now.com/api/sn_sow_synthetics/v1/synthetics_async_bulk_create" \--request POST \--header "Accept:application/json" \--header "Content-Type:application/json" \--data "{  "checks": [    {      "name": "Production API Health Check",      "method": "GET",      "description": "Monitors the main API health endpoint",      "interval": 5,      "cmdb_ci": "21d4073087807610f13cbbf7cebb3500",      "enabled": true,      "should_create_alert": true,      "alert_severity": 1,      "locations": [        "0fd0279b87003210f13cbbf7cebb3552",        "2244a48d87cc7610f13cbbf7cebb3554"      ],      "headers": [        {          "name": "Accept",          "value": "application/json"        }      ],      "query_string": null,      "credential": "",      "body": null,      "parent_service_sys_id": "6731133c87c07610f13cbbf7cebb35d8",      "support_group_sys_id": "019ad92ec7230010393d265c95c260dd",      "alert_tags": {        "environment": "production",        "team": "platform"      },      "valid_http_code_type": "equals",      "valid_http_code": "200",      "max_latency_ms": 5000,      "body_condition": {        "type": "jsonpath",        "expression": "$.status == 'ok'"      }    },    {      "name": "User Service POST Test",      "method": "POST",      "description": "Tests user creation endpoint",      "interval": 10,      "cmdb_ci": "21d4073087807610f13cbbf7cebb3503",      "enabled": true,      "should_create_alert": true,      "alert_severity": 2,      "locations": [        "2244a48d87cc7610f13cbbf7cebb3554"      ],      "headers": [        {          "name": "Content-Type",          "value": "application/json"        }      ],      "body": "{\"test\": true}",      "parent_service_sys_id": "6731133c87c07610f13cbbf7cebb35e1",      "support_group_sys_id": "0762d92db72422103a858bbb4e11a928",      "valid_http_code_type": "in_range",      "valid_http_code": "200-201",      "max_latency_ms": 3000    }  ]}" \--user 'username':'password'

Response body - job successfully created.

JSON
{  "result": {    "job_id": "BCJ-1706789123456-a1b2c3d4",    "job_sys_id": "abc123def456abc123def456",    "status": "pending",    "message": "Job created successfully. File uploaded. Processing will begin shortly.",    "status_check_url": "/api/sn_sow_synthetics/v1/synthetics_async_bulk_create/BCJ-1706789123456-a1b2c3d4"  }}

Response body - concurrent monitor creation job limit error.

JSON
{  "error": {    "code": "CONCURRENT_JOB_LIMIT",    "message": "Maximum concurrent jobs exceeded. Please wait for existing jobs to complete."  }}

Response body - rate limit error.

JSON
{  "error": {    "code": "RATE_LIMIT_EXCEEDED",    "message": "Rate limit exceeded. Please try again later.",    "details": {      "remaining_per_minute": 0,      "remaining_per_hour": 5,      "remaining_per_day": 100    }  }}

cURL request

This example submits a job to create a monitor for an API endpoint that has a parent service relationship in the CI Relationship [cmdb_rel_ci] table.

Shell
curl "https://instance.service-now.com/api/sn_sow_synthetics/v1/synthetics_async_bulk_create" \--request POST \--header "Accept:application/json" \--header "Content-Type:application/json" \--data "{  "checks": [    {      "cmdb_ci": "https://user-mgmt.example.com/api/v2/notifications",      "name": "existing_url_check",      "method": "GET",      "interval": 1,      "locations": [        "335c38f5534332308e4dedeefa7b1314"      ],      "valid_http_code_type": "equals",      "valid_http_code": "200"    }  ]}" \--user 'username':'password'

Response body - job successfully created.

JSON
{  "result": {    "job_id": "BCJ-1809789123456-a1b2c3d5",    "job_sys_id": "abc123def456abc123def456",    "status": "pending",    "message": "Job created successfully. File uploaded. Processing will begin shortly.",    "status_check_url": "/api/sn_sow_synthetics/v1/synthetics_async_bulk_create/BCJ-1809789123456-a1b2c3d5"  }}
Search documentation
Search document titles and file paths on the australia branch