Splunk Observability Cloud Detectors
API for creating, retrieving, updating, and deleting detectors.
OpenAPI Specification
openapi: 3.0.3
info:
title: Splunk Observability Cloud — Detectors
version: 3.10.0
description: 'API for creating, retrieving, updating, and deleting detectors.
Requirements
You must have an organization access token with the API permission or a session token to use the API.
You must have the Splunk Observability Cloud admin or power role to use the POST /detector endpoint, PUT /detector/{id},
PUT /detector/{id}/enable, PUT /detector/{id}/disable, and DELETE /detector/{id} operations.
You must have the Splunk Observability Cloud admin, power, or read_only role to use the GET /detector, GET /detector/{id},GET
/detector/{id}/events, GET /detector/{id}/incidents, and POST /detector/validate operations.'
x-provenance:
method: reconstructed
authored_by: Splunk (content) / API Evangelist (assembly)
reconstructed_by: API Evangelist
reconstructed_on: '2026-08-19'
first_party: false
provider_published: false
note: Splunk's own OpenAPI objects, extracted from the React Server Component payload embedded in each of the 48 API reference
pages at dev.splunk.com. The operations and schemas are Splunk's; the assembly into standalone documents is API Evangelist's.
Splunk serves no fetchable spec file — dev.splunk.com answers 200 with an identical 6,638-byte shell for every asset
path, including invented control paths — so this is NOT first-party publication and is not graded as such.
x-evidence:
- type: source
url: https://dev.splunk.com/observability/reference/
- type: source
url: https://dev.splunk.com/observability/docs/apibasics/api_list/
servers:
- url: https://api.{REALM}.observability.splunkcloud.com/v2
description: Detectors API endpoint URL
variables:
REALM:
default: us0
description: Splunk Observability Cloud realm the organization is provisioned in (for example us0, us1, eu0, jp0, au0).
security:
- SessionToken: []
components:
securitySchemes:
SessionToken:
type: apiKey
in: header
name: X-SF-Token
description: Splunk Observability Cloud session token or org access token.
paths:
/detector:
get:
summary: Retrieve Detectors Query
description: 'Retrieves the properties of one or more detectors. If you don''t
specify any query parameters, the API returns up to the first 50
detector objects that you have access to.'
parameters:
- name: limit
in: query
description: 'Number of results to return from the list of detectors that match your search criteria.
Together, the offset and limit properties provide paged access to the query results. You can repeatedly download
small slices of a large query result, which
helps you avoid bandwidth and performance problems.'
schema:
type: integer
format: int32
default: 50
example: 100
maximum: 10000
minimum: 0
- name: name
in: query
description: 'Search criteria that the API tries to match to the name property
of existing detectors. The match can be full or partial. If the
string is empty, it''s ignored and the API uses the other criteria in
the query. For example, a value of "per" matches detectors for which
the name contains "dropped per day", "95th percentile", or "personal
disk usage".'
schema:
type: string
- name: offset
in: query
description: 'Index, in the list of detectors that match your search criteria, at
which you want to start downloading results.
Together, the offset and limit properties provide paged access to
the query results. You can repeatedly download small slices of a large
query result, which helps you avoid bandwidth and performance problems.'
schema:
type: integer
format: int32
default: 0
minimum: 0
- name: orderBy
in: query
description: The field on which the API should sort the query results. The API only supports fields specified in the
enum.
schema:
type: string
enum:
- creator
- created
- description
- lastUpdated
- lastUpdatedBy
- name
- tags
default: lastUpdated
- name: tags
in: query
description: 'Search criteria that the API applies to the elements of the tags
array property of detectors. The string must be an exact match.
You can specify multiple tags parameters in the same request.'
schema:
type: string
- name: prefixTags
in: query
description: 'Search filter that the API applies to find and return only detectors
which have at least one tag starting with the provided prefix,
for each prefix provided.'
schema:
type: array
items:
type: string
- name: prefixTagExclusions
in: query
description: 'Search filter that the API applies to exclude detectors which have at least one
tag starting with any of the provided prefixes from the query result.'
schema:
type: array
items:
type: string
- name: Content-Type
in: header
description: Format of the request body. Always "application/json".
required: true
schema:
type: string
- name: X-SF-TOKEN
in: header
description: Authentication token
required: true
schema:
type: string
responses:
'200':
description: HTTP 200 response
content:
application/json:
schema:
title: Valid Get Detectors Response
type: object
properties:
count:
title: Count of matched detectors
type: integer
format: int32
readOnly: true
example: 25
description: 'Number of detectors that match the search criteria.
This property is read-only; it''s always set by the system.
Note: Count isn''t the same as the number of detectors returned
in the response body:
sizeOf(results): Size of the array returned in the response body.
count: Number of objects that match the search criteria'
results:
type: array
items:
title: Detector Properties Object
type: object
properties:
authorizedWriters:
title: Organizations and teams with write permission for an object
type: object
properties:
teams:
type: array
items:
type: string
example: DevOps
description: 'List of team IDs that have write access to this object, in the form
of a JSON array'
users:
type: array
items:
type: string
example: AAXYAAAAAZ4
description: 'List of user IDs that have write access to this object, in the form
of a JSON array'
description: 'If your organization has the write permissions feature enabled, you
can use this property to specify the user and team IDs that have write
access to the object you''re specifying.'
created:
title: Creation time
type: integer
format: int64
example: 1556825430000
readOnly: true
description: 'The time the detector was created, in *nix time in milliseconds.
This property is read-only; it''s always set by the system.'
creator:
title: Creator user ID
type: string
example: AAXYAAAAAZ3
readOnly: true
description: 'Splunk Observability Cloud ID of the user who created the detector.
This property is read-only; it''s always set by the system.'
customProperties:
title: Custom properties
type: object
additionalProperties: null
readOnly: false
writeOnly: false
example:
property1: detectorArea
value1: internal detectors
description: Metadata for a detector, in the form of a JSON object.
description:
title: Detector description
type: string
readOnly: false
writeOnly: false
example: jvm CPU load warning
description: 'Description of a detector. The value appears in the Detector window
displayed in the UI Actions menu.'
detectorOrigin:
title: How the detector was created
type: string
enum:
- Standard
- AutoDetect
- AutoDetectCustomization
example: Standard
default: Standard
description: 'Indicates how a detector was created. The possible values are:
Standard: Detector created using the API or the user interface.
AutoDetect: Detector is an AutoDetect detector created by Splunk Observability Cloud.
AutoDetectCustomization: Detector is a customization of another AutoDetect detector.
Note: You can only use Standard or AutoDetectCustomization to create custom detectors. If you
try to pass an invalid value for detectorOrigin when creating or updating detectors, you receive
a "Not valid detector origin" error message in the response.'
id:
title: Detector system ID
type: string
readOnly: true
description: 'ID of a detector. When you retrieve events
or incidents for a detector, this ID is for the detector that
generated the event or incident.
This property is read-only; it''s always set by the system.'
labelResolutions:
title: Alert resolution times
type: object
readOnly: true
additionalProperties:
type: integer
example:
DetectorA: 3000
DetectorB: 5000
description: 'Key-value pairs that indicate how often data is analyzed to determine if an
alert should be triggered, in the form of a JSON object containing
properties. Each key is the label name of a call to publish() in the
SignalFlow for the detector, and each value is the resolution time
for that publish() block.
For example, to retrieve the label resolution of the call to
publish("DetectorStatement") from this object, use
labelResolutions.DetectorStatement.
Label resolution is different from the data display resolution used to
populate the detector visualization. The data display resolution is
automatically set to the coarsest resolution of all of the SignalFlow
publish() calls associated with the detector, since they are all
displayed together in the same visualization.'
lastUpdated:
title: Detector last updated time
type: integer
format: int64
example: 1557689430000
readOnly: true
description: The last time the detector was updated, in *nix time in milliseconds.
lastUpdatedBy:
title: Detector last updated ID
type: string
readOnly: true
example: ZZyZZZZXXXQ
description: 'The ID of the user who last updated the detector. If the system made the last update,
the value is "AAAAAAAAAA".
This property is read-only; it''s always set by the system.'
locked:
title: Detector lock state
type: boolean
example: false
description: 'Detector lock state. If true, nobody can modify the detector in any
way; otherwise, anyone can modify it.'
maxDelay:
title: Late-arriving data point delay time
type: integer
format: int32
minimum: 0
maximum: 900000
default: 0
readOnly: false
writeOnly: false
example: 60000
description: 'Sets a duration, in milliseconds, to wait for late-arriving data before continuing
the SignalFlow computation
for the detector. If data is arriving on time, the computation continues before the duration expires.
The default is 0, which tells SignalFlow to set the limit dynamically.
To set a duration to wait even if data is arriving on time, use minDelay.'
minDelay:
title: data point pre-processing delay time
type: integer
format: int32
minimum: 0
maximum: 900000
readOnly: false
writeOnly: false
example: 60000
description: 'Sets a duration, in milliseconds, to wait before continuing the SignalFlow computation
for the detector.
The computation waits for this duration to expire, even if the data is arriving in a timely fashion.
To set a duration to wait for late-arriving data, use maxDelay.'
name:
title: Detector name (displayed)
type: string
minLength: 1
readOnly: false
writeOnly: false
example: JVM CPU Load detector
description: 'Displayed name of the detector in the UI. When you
retrieve events or incidents, this property contains the name of the
associated detector.'
overMTSLimit:
type: boolean
readOnly: true
example: false
title: OverMTSLimit
description: 'If true, one or more statements in a detector matched too many MTS,
and the system forcibly limited the detector. This usually occurs when
the detector is looking at incomplete data or an incomplete
aggregation. When this flag is true, use partition_filter()
functions to split your dataset into smaller pieces, then use the
union() function to rejoin the results in a subsequent computation.
The union() function still observes the MTS limit, so an
aggregation of the partial streams must first limit the dataset prior
to recombining the streams.
This property is read-only; it''s always set by the system.'
parentDetectorId:
title: ID of the parent AutoDetect detector
type: string
description: ID of the parent detector from which this detector is customized and created. This
property is required for detectors with detectorOrigin of type AutoDetectCustomization.
packageSpecifications:
title: SignalFlow internal field
type: string
default: ''
description: For internal use only
programText:
title: SignalFlow program for the detector
type: string
readOnly: false
writeOnly: false
example: cpuLoad = data('jvm.cpu.load').percentile(pct=94).publish(label='cpuLoad'); detect(when(cpuLoad
> 94)).publish('cpuLoad');
description: 'Specifies the SignalFlow program that defines the detector. This program
must include one or more calls to the SignalFlow detect() function.
The program must also call publish() on each detect stream, using a
label that''s unique to the program.
If you want to use custom notification messages that include input data,
assign your detect conditions to variables.
To use multiple lines in your program, terminate each line with a
semicolon ; or newline character \n.
To learn more about SignalFlow programs for detectors,
see the Detectors topic in the Developers Guide.
Note: For detectors with detectorOrigin of type AutoDetectCustomization, it is best practice to
keep the same function in the programText property as the parent detector. You can still pass
different arguments for the function.'
rules:
title: Alert Rule Definitions
type: array
items:
title: Detector Rule Object
type: object
required:
- detectLabel
- severity
properties:
description:
type: string
default: ''
readOnly: false
writeOnly: false
example: JVM CPU Load test
title: RuleDescription
description: 'Description for the rule. Displays as the alert condition in the
Alert Rules tab of the detector editor in the UI'
detectLabel:
type: string
example: cpuLoad
title: RuleDetectLabel
description: 'Label of the publish() call for the detect() function associated
with this rule.'
disabled:
type: boolean
default: false
readOnly: false
writeOnly: false
example: false
title: Disabled
description: 'Controls the state of an alert rule. If false, the rule is turned on
and SignalFlow issues alerts for it. If true, the rule is turned
off and SignaFlow doesn''t issue alerts for it, even if one of the
rules is triggered.'
notifications:
type: array
readOnly: false
writeOnly: false
items:
oneOf:
- title: Amazon EventBridge Alert Notification
type: object
required:
- type
- credentialId
properties:
type:
type: string
readOnly: false
writeOnly: false
example: AmazonEventBridge
description: 'Tells Splunk Observability Cloud which external system it should use
to send the
notification. For an Amazon EventBridge notification, this is always
"AmazonEventBridge".'
credentialId:
type: string
readOnly: false
writeOnly: false
description: 'Amazon EventBridge integration identifier, which Splunk Observability
Cloud assigns
when you add the integration. Use the UI or the Integrations API
to find the value of credentialId.'
description: 'Specifies the properties needed to send a notification from a detector
to an existing Splunk Observability Cloud-to-Amazon EventBridge integration'
- title: BigPanda Alert Notification
type: object
required:
- type
- credentialId
properties:
type:
type: string
readOnly: false
writeOnly: false
example: BigPanda
description: 'Tells Splunk Observability Cloud which external system it should use
to send the
notification. For a BigPanda notification, this is always
"BigPanda".'
credentialId:
type: string
readOnly: false
writeOnly: false
description: 'BigPanda integration identifier, which Splunk Observability Cloud assigns
when you add
the integration. Use the UI or the Integrations API to find the
value of credentialId.'
description: 'Specifies the properties of a notification service integration between
BigPanda and Splunk Observability Cloud, in the form of a JSON object'
- title: Email Alert Notification
type: object
required:
- email
- type
properties:
type:
type: string
readOnly: false
writeOnly: false
example: Email
description: 'Tells Splunk Observability Cloud which external system it should use
to send the
notification. For an email notification, this is always "Email".'
email:
type: string
readOnly: false
writeOnly: false
example: info@example.com
description: 'The destination address for the notification email. Splunk Observability
Cloud doesn''t
validate this address, so you must ensure it''s correct before you
use it. Splunk Observability Cloud may not store invalid values, and it may try
to
send notification email that doesn''t have an address. In either
case, the notification won''t be delivered.'
description: 'Specifies the properties of a notification service integration between
email and Splunk Observability Cloud, in the form of a JSON object'
- title: Jira Cloud or Jira Server Alert Notification
type: object
required:
- type
- credentialId
properties:
type:
type: string
readOnly: false
writeOnly: false
example: Jira
description: 'Tells Splunk Observability Cloud which external system it should use
to send the
notification. For a Jira Cloud or Jira Server notification, this is
always "Jira".'
credentialId:
type: string
readOnly: false
writeOnly: false
description: 'Jira integration identifier, which Splunk Observability Cloud assigns
when you add
the integration. Use the UI or the Integrations API to find the
value of credentialId.'
description: 'Specifies the properties of a notification service integration between
Jira Cloud or Jira Server and Splunk Observability Cloud, in the form of a JSON object.
Jira alert notifications take the form of a new Jira ticket whose
properties are specified in the Jira integration object.
For more information, see the Integrate Jira with Splunk Observability Cloud topic in
the Developers Guide.'
- title: Microsoft Teams Alert Notification
type: object
required:
- type
- credentialId
properties:
type:
type: string
readOnly: false
writeOnly: false
example: Office365
description: 'Tells Splunk Observability Cloud which external system it should use
to send the
notification. To ensure backwards compatibility, this is always
"Office365".'
credentialId:
readOnly: false
writeOnly: false
type: string
description: 'Microsoft Teams integration identifier, which Splunk Observability Cloud
assigns when you
add the integration. Use the UI or the Integrations API to find
the value of credentialId.'
description: 'Specifies the properties of a notification service integration between
Microsoft Teams and Splunk Observability Cloud, in the form of a JSON object'
- title: Opsgenie Alert Notification
type: object
required:
- credentialId
- type
properties:
type:
type: string
readOnly: false
writeOnly: false
example: Opsgenie
description: 'Tells Splunk Observability Cloud which external system it should use
to send the
notification. For an Opsgenie notification, this is always
"Opsgenie".'
credentialId:
type: string
description: 'Opsgenie integration identifier, which Splunk Observability Cloud assigns
# --- truncated at 32 KB (533 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/splunk-observability/refs/heads/main/openapi/splunk-observability-detectors-openapi.yml