SyntheticsAsyncBulkCreate API

  • Release version: Yokohama
  • Updated April 20, 2026
  • 12 minutes to read

    • 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. Additionally, configuration items (CIs) for the endpoints being monitored must exist in the Configuration Management Database (CMDB).

    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

    Table 1. Path 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
    Table 2. Query parameters
    Name Description
    None
    Table 3. Request body parameters
    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.

    Table 4. Request 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>
    Table 5. Response headers
    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.

    Table 6. Status 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}.

    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

    Table 7. Path 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
    Table 8. Query parameters
    Name Description
    None
    Table 9. Request body parameters (JSON or CSV)
    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).

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

    Table 10. Request 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
    Table 11. Response headers
    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.

    Table 12. Status 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
    }
  }
}