REST API reference › API reference › API implementation and reference

Release: Australia · Updated: 2026-04-20 · Official documentation · View source

SyntheticsAsyncBulkCreate API

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: `Authorization: Basic <base64-encoded-username:password>` OAuth format: `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 `"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 `"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 `"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 `"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.

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.

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

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

{
   "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 "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. `//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 `"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\) `"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: `Authorization: Basic <base64-encoded-username:password>` OAuth format: `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 `"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 `"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.

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.

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

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

Response body - rate limit error.

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

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.

{
  "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"
  }
}