.conf25 registration is now open!Register today
Search

Synthetics Port tests latest

API for creating, updating, retrieving, and deleting Port tests in Splunk Synthetic Monitoring.

Requirements

  • You must have an organization access token with the API permission or a session token to use the API.
  • You have to have the Splunk Observability Cloud admin or power role to use the POST /tests/port/try_now, POST /tests/port/validate, PUT /tests/port/{id}/validate, POST /tests/port, PUT /tests/port/{id}, and DELETE /tests/port/{id} operations.
  • You have to thave the Splunk Observability Cloud admin, power, or read_only role to use the GET /tests/port/{id} operation.
API Base URL
https://api.{REALM}.signalfx.com/v2/synthetics
Copy to clipboard

Endpoint URL

 
POST
/tests/port
Copy full endpoint URL to clipboard

Creates a new Port test, based on the specifications in the request body.

Requirements

  • You must have an organization access token with the API permission or a session token to use the API.
  • You need the Splunk Observability Cloud admin or power role.
Headers
Name
Description
Content-Type
Required
string

Format of the request body. Always "application/json".

X-SF-TOKEN
Required
string

Authentication token.

Code Examples
cURL
HTTP
curl -X POST "https://api.{REALM}.signalfx.com/v2/synthetics/tests/port" \
    -H "Content-Type: application/json" \
    -H "X-SF-TOKEN: <value>" \
    -d '{
            "test": {
                "active": true,
                "automaticRetries": 1,
                "customProperties": [
Copy to clipboard
...
Request Body
Content Type: application/json

Properties of a new Port test.

Note: You can't create properties for fields that are marked read-only.

Name
Description
test
object
Request Examples
Content Type: application/json
Collapse children
Copy to clipboard
{
  test: {
    active: true,
    automaticRetries: 1,
    customProperties: [
      {
        key: "Env",
        value: "production"
      }
    ],
    frequency: 5,
    host: "splunk.com",
    locationIds: [
      "aws-us-east-1"
    ],
    name: "My Port Test",
    port: 0,
    protocol: "tcp",
    schedulingStrategy: "round_robin"
  }
}
Response Body
Content Type: application/json

Successful creation of a test.

Name
Description
test
object
Response Examples
Content Type: application/json
Collapse children
Copy to clipboard
{
  test: {
    active: true,
    automaticRetries: 1,
    createdAt: "2022-09-14T14:35:37.801Z",
    createdBy: "abcdefgh1234",
    customProperties: [
      {
        key: "Env",
        value: "production"
      }
    ],
    frequency: 5,
    host: "splunk.com",
    id: 1,
    lastRunAt: "2022-09-14T14:36:45.156Z",
    lastRunStatus: "success",
    locationIds: [
      "aws-us-east-1"
    ],
    name: "My Port Test",
    port: 443,
    protocol: "tcp",
    schedulingStrategy: "round_robin",
    type: "http",
    updatedAt: "2022-09-14T14:35:38.099Z",
    updatedBy: "abcdefgh1234"
  }
}
 
POST
/tests/port/try_now
Copy full endpoint URL to clipboard

Create a port test to use try now on to verify if your test passes. Run results aren't stored.

Requirements

  • You must have an organization access token with the API permission or a session token to use the API.
  • You need the Splunk Observability Cloud admin or power role.
Headers
Name
Description
Content-Type
Required
string

Format of the request body. Always "application/json".

X-SF-TOKEN
Required
string

Authentication token.

Query Parameters
Name
Description
locationId
Required
string
Example: aws-us-east-1

The ID of the location to run your test from.

Code Examples
cURL
HTTP
curl -X POST "https://api.{REALM}.signalfx.com/v2/synthetics/tests/port/try_now" \
    -H "Content-Type: application/json" \
    -H "X-SF-TOKEN: <value>" \
    -d '{
            "test": {
                "active": true,
                "automaticRetries": 1,
                "customProperties": [
Copy to clipboard
...
Request Body
Content Type: application/json

Properties of a Port test.

Note: You can't create properties for fields that are marked read-only.

Name
Description
test
object
Request Examples
Content Type: application/json
Collapse children
Copy to clipboard
{
  test: {
    active: true,
    automaticRetries: 1,
    customProperties: [
      {
        key: "Env",
        value: "production"
      }
    ],
    frequency: 5,
    host: "splunk.com",
    locationIds: [
      "aws-us-east-1"
    ],
    name: "My Port Test",
    port: 0,
    protocol: "tcp",
    schedulingStrategy: "round_robin"
  }
}
Response Body
Content Type: application/json

Successful POST

Name
Description
runId
string <uuid>
Example: 1c4d52be-e7e1-4611-97f9-73c6ddfbeed9

The UUID of the generated run

testId
string <uuid>
Example: b8354c68-3fe8-4192-81b2-a4f7cb40e18b

The UUID of the try now test

Response Examples
Content Type: application/json
Copy to clipboard
{
  runId: "1c4d52be-e7e1-4611-97f9-73c6ddfbeed9",
  testId: "b8354c68-3fe8-4192-81b2-a4f7cb40e18b"
}
 
POST
/tests/port/validate
Copy full endpoint URL to clipboard

Validate a Port test.

Requirements

  • You must have an organization access token with the API permission or a session token to use the API.
  • You need the Splunk Observability Cloud admin or power role.
Headers
Name
Description
Content-Type
Required
string

Format of the request body. Always "application/json".

X-SF-TOKEN
Required
string

Authentication token.

Code Examples
cURL
HTTP
curl -X POST "https://api.{REALM}.signalfx.com/v2/synthetics/tests/port/validate" \
    -H "Content-Type: application/json" \
    -H "X-SF-TOKEN: <value>" \
    -d '{
            "test": {
                "active": true,
                "automaticRetries": 1,
                "customProperties": [
Copy to clipboard
...
Request Body
Content Type: application/json

Properties of an port test.

Note: You can't create properties for fields that are marked read-only.

Name
Description
test
object
Request Examples
Content Type: application/json
Collapse children
Copy to clipboard
{
  test: {
    active: true,
    automaticRetries: 1,
    customProperties: [
      {
        key: "Env",
        value: "production"
      }
    ],
    frequency: 5,
    host: "splunk.com",
    locationIds: [
      "aws-us-east-1"
    ],
    name: "My Port Test",
    port: 0,
    protocol: "tcp",
    schedulingStrategy: "round_robin"
  }
}
Response Body
Content Type: application/json

Successful POST

Name
Description
details
object

Details of why Port test is invalid. The frequency key in the example is dynamic. If frequency is invalid, the key will be frequency. If port is invalid, there will be a port key, etc.

If the test is valid, this details field will be an empty array, [].

message
string
Example: Port Test is not valid.
valid
boolean
Response Examples
Content Type: application/json
Collapse children
Copy to clipboard
{
  details: {
    frequency: [
      "must be greater than or equal to 1"
    ]
  },
  message: "Port Test is not valid.",
  valid: false
}
 
GET
/tests/port/{id}id (string): The ID of a Port to retrieve.
Copy full endpoint URL to clipboard

Retrieves a single Port test.

Requirements

  • You must have an organization access token with the API permission or a session token to use the API.
  • You need the Splunk Observability Cloud admin, power, or read_only role.
Headers
Name
Description
X-SF-TOKEN
Required
string

Authentication token.

Path Parameters
Name
Description
id
Required
string

The ID of a Port to retrieve.

Code Examples
cURL
HTTP
curl -X GET "https://api.{REALM}.signalfx.com/v2/synthetics/tests/port/{id}" \
    -H "Content-Type: application/json" \
    -H "X-SF-TOKEN: <value>"
Copy to clipboard
Response Body
Content Type: application/json

Successful retrieval of a Port test.

Name
Description
active
boolean
Example: true
automaticRetries
integer
Default: 0
Example: 1

Automatically retry if the run fails

createdAt
string
Example: 2022-09-14T14:35:37.801Z

Timestamp of when the test was last updated, in UTC. This field is read-only, and the system always sets the value.

createdBy
string
Example: abcdefgh1234

Member ID of who created the test. This field is read-only, and the system always sets the value.

customProperties
array[object]

An array of custom properties. The section Custom Properties Criteria lists the requirements for custom property names and values.

frequency
integer <int32>
Example: 5

How often to run your test.

host
string
Example: splunk.com
id
integer <int32>
Example: 1
lastRunAt
string
Example: 2022-09-14T14:36:45.156Z

Timestamp of when the test was last run, in UTC. This field is read-only, and the system always sets the value.

lastRunStatus
string
Example: success

Status of the last test run.

locationIds
array[string]
Example: 
[
  "aws-us-east-1"
]

An array of location IDs where the test runs.

name
string
Example: My Port Test
port
integer <int32>
Example: 443
protocol
string
Example: tcp
schedulingStrategy
string
Example: round_robin

Type of scheduling strategy. This can only be:

  • round_robin
  • concurrent
type
string
Example: http
updatedAt
string
Example: 2022-09-14T14:35:38.099Z

Timestamp of when the test was last updated, in UTC. This field is read-only, and the system always sets the value.

updatedBy
string
Example: abcdefgh1234

Member ID of who last updated the test. This field is read-only, and the system always sets the value.

Response Examples
Content Type: application/json
Collapse children
Copy to clipboard
{
  active: true,
  automaticRetries: 1,
  createdAt: "2022-09-14T14:35:37.801Z",
  createdBy: "abcdefgh1234",
  customProperties: [
    {
      key: "Env",
      value: "production"
    }
  ],
  frequency: 5,
  host: "splunk.com",
  id: 1,
  lastRunAt: "2022-09-14T14:36:45.156Z",
  lastRunStatus: "success",
  locationIds: [
    "aws-us-east-1"
  ],
  name: "My Port Test",
  port: 443,
  protocol: "tcp",
  schedulingStrategy: "round_robin",
  type: "http",
  updatedAt: "2022-09-14T14:35:38.099Z",
  updatedBy: "abcdefgh1234"
}
 
PUT
/tests/port/{id}id (integer): The ID of the Port test you want to validate.
Copy full endpoint URL to clipboard

Update an existing Port test.

Requirements

  • You must have an organization access token with the API permission or a session token to use the API.
  • You need the Splunk Observability Cloud admin or power role.
Headers
Name
Description
Content-Type
Required
string

Format of the request body. Always "application/json".

X-SF-TOKEN
Required
string

Authentication token.

Path Parameters
Name
Description
id
Required
integer
Example: 1

The ID of the Port test you want to validate.

Code Examples
cURL
HTTP
curl -X PUT "https://api.{REALM}.signalfx.com/v2/synthetics/tests/port/{id}" \
    -H "Content-Type: application/json" \
    -H "X-SF-TOKEN: <value>" \
    -d '{
            "test": {
                "active": true,
                "automaticRetries": 1,
                "customProperties": [
Copy to clipboard
...
Request Body
Content Type: application/json

Properties of a Port test.

Note: You can't create properties for fields that are marked read-only.

Name
Description
test
object
Request Examples
Content Type: application/json
Collapse children
Copy to clipboard
{
  test: {
    active: true,
    automaticRetries: 1,
    customProperties: [
      {
        key: "Env",
        value: "production"
      }
    ],
    frequency: 5,
    host: "splunk.com",
    locationIds: [
      "aws-us-east-1"
    ],
    name: "My Port Test",
    port: 0,
    protocol: "tcp",
    schedulingStrategy: "round_robin"
  }
}
Response Body
empty

The response body will be blank

Response Examples
Content Type: application/json
Collapse children
Copy to clipboard
{
  code: "not_found",
  details: {},
  message: "Can't find test."
}
 
DELETE
/tests/port/{id}id (string): The ID of a test.
Copy full endpoint URL to clipboard

Deletes a Port test.

Requirements

  • You must have an organization access token with the API permission or a session token to use the API.
  • You need the Splunk Observability Cloud admin or power role.
Headers
Name
Description
X-SF-TOKEN
Required
string

Authentication token.

Path Parameters
Name
Description
id
Required
string

The ID of a test.

Code Examples
cURL
HTTP
curl -X DELETE "https://api.{REALM}.signalfx.com/v2/synthetics/tests/port/{id}" \
    -H "Content-Type: application/json" \
    -H "X-SF-TOKEN: <value>"
Copy to clipboard
Response Body
empty

Successful deletion of a test.

 
PUT
/tests/port/{id}id (integer): The ID of the Port test you want to validate. /validate
Copy full endpoint URL to clipboard

Validate an port test. This can also be a PATCH operation.

Requirements

  • You must have an organization access token with the API permission or a session token to use the API.
  • You need the Splunk Observability Cloud admin or power role.
Headers
Name
Description
Content-Type
Required
string

Format of the request body. Always "application/json".

X-SF-TOKEN
Required
string

Authentication token.

Path Parameters
Name
Description
id
Required
integer
Example: 1

The ID of the Port test you want to validate.

Code Examples
cURL
HTTP
curl -X PUT "https://api.{REALM}.signalfx.com/v2/synthetics/tests/port/{id}/validate" \
    -H "Content-Type: application/json" \
    -H "X-SF-TOKEN: <value>" \
    -d '{
            "test": {
                "active": true,
                "automaticRetries": 1,
                "customProperties": [
Copy to clipboard
...
Request Body
Content Type: application/json

Properties of an Port test.

Note: You can't create properties for fields that are marked read-only.

Name
Description
test
object
Request Examples
Content Type: application/json
Collapse children
Copy to clipboard
{
  test: {
    active: true,
    automaticRetries: 1,
    customProperties: [
      {
        key: "Env",
        value: "production"
      }
    ],
    frequency: 5,
    host: "splunk.com",
    locationIds: [
      "aws-us-east-1"
    ],
    name: "My Port Test",
    port: 0,
    protocol: "tcp",
    schedulingStrategy: "round_robin"
  }
}
Response Body
Content Type: application/json

Successful validation request of a test

Name
Description
details
object

Details of why Port test is invalid. The frequency key in the example is dynamic. If frequency is invalid, the key will be frequency. If port is invalid, there will be a port key, etc.

If the test is valid, this details field will be an empty array, [].

message
string
Example: Port Test is not valid.
valid
boolean
Response Examples
Content Type: application/json
Collapse children
Copy to clipboard
{
  details: {
    frequency: [
      "must be greater than or equal to 1"
    ]
  },
  message: "Port Test is not valid.",
  valid: false
}

Splunk, Splunk ›, Listen to Your Data, The Engine for Machine Data, Splunk Cloud, Splunk Light and SPL are trademarks and registered trademarks of Splunk Inc. in the United States and other countries. All other brand names, product names, or trademarks belong to their respective owners. © 2025 Splunk Inc. All rights reserved.