Splunk Observability Cloud Retrieve events V2
The Retrieve events V2 API from Splunk Observability Cloud — 1 operation(s) at https://api.{REALM}.observability.splunkcloud.com/v2.
OpenAPI Specification
openapi: 3.0.3
info:
title: Splunk Observability Cloud — Retrieve events V2
version: 1.0.0
description: 'V2 API for retrieving events.
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, power user, or read_only role to use this API.'
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: API for retrieving events.
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:
/event/find:
get:
summary: Retrieve Events Using Query
description: 'Retrieves events from Splunk Observability Cloud, based on
query parameters you specify. The operation retrieves detector
events as well as custom events.
Note: Splunk Observability Cloud returns a maximum of 10,000 events, even if your organization contains more than
10,000. To learn more, see the
Considerations for retrieve operations section in the developer guide.
The operation provides these query parameters:
The query query parameter specifies name- and value-based
search criteria.
The fields query parameter specifies custom fields to return values for. You can add multiple fields to one query.
The start_time and end_time query parameters specify the boundaries of a time window from which
you want to retrieve datapoints.
The offset parameter specifies the point in the query results at
which the API should start sending event data.
The limit parameter specifies the number of results to send.
The order_by parameter controls the order of the results you receive.
The API combines the query results and the time window with a logical AND.
This API doesn''t take a request body.
Requirements
You must have an organization access token with the API permission or a session token to use this endpoint.
You must have the Splunk Observability Cloud admin, power role, or read_only role.'
parameters:
- name: query
in: query
description: 'Search criteria that specifies the events that you want the
API to return. You can search for any of the event properties.
You might need to use different forms of a field name in the
query parameter:
To search for eventType, use sf_eventType.
To search for category, use sf_eventCategory.
You have to specify at least one value for query.
Search criteria have the following rules:
To search for specific values of a dimension or property, specify
<name>:<value>. If <value> contains
non-alphanumeric characters, encode the non-alphanumeric characters and surround the value with
double quotes. For example, the region custom property value US East must be passed in the parameter as region:"US%20East".
To search for names or values using wildcards, use * as the
wildcard character.
Join searches with NOT, AND, and OR operators.
Use parentheses ''('' and '')'' to change the evaluation order.'
required: true
schema:
type: string
- name: fields
in: query
schema:
type: string
- name: start_time
in: query
description: 'Start of the time window from which the API should retrieve custom
events. Specify the value in *nix time in milliseconds, and remember to
correct for your time zone.
If the value is negative, the API interprets it as an offset before
the current server time (UTC).
If you specify start_time but not end_time, the time window extends to the
current server time.'
schema:
type: integer
format: int64
- name: limit
in: query
description: 'The number of events to retrieve from the result set:
The maximum is 9,999, because the first retrieved event is result 0.
The default is 1000.
If you specify -1, the API returns 1000 results.
Regardless of the value of offset, requesting more than
10,000 results results in an HTTP response code 500.'
schema:
type: integer
format: int32
maximum: 9999
- name: offset
in: query
description: 'The index in the query result set at which the API should start
sending results to you. For example, 0 is first result in the set, and
10 is the 11th result.'
schema:
type: integer
format: int32
- name: order_by
in: query
description: 'The field on which the API should sort the query results. The value
can be any event property, including metadata.
Prepend a - character to the property name to sort in descending order. If you want to apply order_by to non-custom
property fields like timestamp, prepend the field with sf_. For example: order_by=-sf_timestamp.'
schema:
type: string
- name: end_time
in: query
description: 'End of the time window from which the API should retrieve custom
events. Specify the value in *nix time in milliseconds and remember to
correct for your time zone.
If the value is negative, the API interprets it as an offset before
the current server time (UTC).
If you specify end_time but not start_time, the time window extends from the
earliest event to the value of end_time.'
schema:
type: integer
format: int64
- name: X-SF-Token
in: header
description: Authentication token
required: true
schema:
type: string
responses:
'200':
description: HTTP 200 response
content:
application/json:
schema:
type: array
maxItems: 10000
minItems: 0
items:
type: object
properties:
id:
type: string
example: AddBYZrEFEF
description: ID of the event, assigned by Splunk Observability Cloud
metadata:
type: object
additionalProperties: true
example:
ETS_key1: detector
ETS_key2: false
ETS_key3: 1001
description: 'A map of key-value pairs created by Splunk Observability Cloud from
event time series metadata for the ETS that the event belongs to.
For example, alerts received from AWS contain metadata that describes
the AWS instance that sent the alert.'
properties:
type: object
additionalProperties: true
example:
is: ok
sf_notificationWasSent: true
was: anomalous
description: 'A map of key-value pairs. The map can contain data sent to
Splunk Observability Cloud in a POST v2/event request. It can also contain
data added to the event from other sources.'
sf_eventCategory:
type: string
enum:
- USER_DEFINED
- ALERT
- AUDIT
- JOB
- COLLECTED
- SERVICE_DISCOVERY
- EXCEPTION
description: 'A category that describes the event. The values are a set of enumerated types.
Splunk Observability Cloud sets some values, while you can set others:
USER_DEFINED: The default for events
ALERT: Used by Splunk Observability Cloud to mark an event generated by
a detector.
AUDIT: Used by third-party integrations
JOB: Event generated by an Splunk Observability Cloud or third-party
background job
COLLECTD: Generated by the Splunk Observability Cloud collectd integration
SERVICE_DISCOVERY: Generated by third-party integrations
EXCEPTION: A software exception occurred'
sf_eventCreatedOnMs:
type: integer
format: int64
readOnly: true
example: 1553678621002
description: The date and time when the alert that creates the event was set, in *nix time in milliseconds.
sf_eventType:
type: string
description: 'A name for the event. You can specify this value when you send a
custom event to Splunk Observability Cloud. Use it to uniquely identify
custom events.
For an event time series, this value is the analog of the metric
name in a metric time series.'
timestamp:
type: integer
format: int64
readOnly: true
example: 1554672630000
description: The date and time of the event in *nix time in milliseconds. It's set by system.
tsId:
type: string
example: XzZYApXCDCD
description: 'Splunk Observability Cloud-assigned ID of the event time series (ETS) this
event belongs to'
title: EventResponseObject
description: Specifies a single event
examples:
example:
value:
- id: AddBYZrEFEF
metadata:
ETS_key1: detector
ETS_key2: false
ETS_key3: 1001
properties:
is: ok
sf_notificationWasSent: true
was: anomalous
sf_eventCategory: USER_DEFINED
sf_eventCreatedOnMs: 1553678621002
sf_eventType: string
timestamp: 1554672630000
tsId: XzZYApXCDCD
'406':
description: HTTP 406 response
content:
application/json:
schema:
type: object
properties:
code:
type: integer
description: HTTP response code. Always 406.
message:
type: string
description: Error message
example:
code: 406
message: At least one filtration clause must be specified.
examples:
example:
value:
code: 406
message: At least one filtration clause must be specified.
'500':
description: HTTP 500 response
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 500
description: HTTP response code. Always 500.
message:
type: string
example: Server error occurred. Unique error identifier [<error_id>]
description: Error message, including a unique error identifier
examples:
example:
value:
code: 500
message: Server error occurred. Unique error identifier [<error_id>]
security:
- SessionToken: []
tags:
- Retrieve events V2