Splunk Observability Cloud Client Inventory API

openapi: 3.2.0
info:
  title: Splunk Observability Cloud Client Inventory API
  version: 1.0.0
  description: 'REST API for managing OpAMP client inventory.

    Use this API to browse registered clients, inspect individual client records, and retrieve the effective configuration currently associated with a client.

    Deployment

    This API is shared by multiple products. Public server URLs and authentication requirements are supplied by product-specific publication overlays. All endpoints are relative to /fm-service/v1.

    Endpoints


    GET /clients List clients

    GET /clients/metadata/values List distinct client metadata values

    GET /clients/{id} Get client by ID

    GET /clients/{id}/config Get client effective configuration

    POST /clients/configs:batch Batch get client effective configurations


    Splunk Observability Cloud

    Replace {REALM} with your Splunk Observability Cloud realm.

    Send an access token in the X-SF-TOKEN header.

    Example: X-SF-TOKEN: <X-SF-TOKEN>'
  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/fm-service/v1
  description: Splunk Observability Cloud Client Inventory API
  variables:
    REALM:
      default: us0
      description: Splunk Observability Cloud realm the organization is provisioned in (for example us0, us1, eu0, jp0, au0).
security:
- SessionToken: []
tags:
- name: Client Inventory
paths:
  /clients:
    get:
      summary: listClients
      parameters:
      - name: limit
        in: query
        description: 'Size of page (number of items to return). The server enforces a configurable maximum (default: 1000).'
        schema:
          default: 100
          minimum: 1
          type: integer
      - name: offset
        in: query
        description: Offset for pagination (number of items to skip)
        schema:
          default: 0
          minimum: 0
          type: integer
      - name: include_health
        in: query
        description: 'Whether to include health data in the response. Default: true. Set to false to exclude health data for analytical queries.'
        schema:
          default: true
          type: boolean
      - name: healthy
        in: query
        description: 'Filter by top-level health status. Repeat to match any selected state. At most 10 healthy values are accepted per request. When omitted, no health filtering is applied.


          true — only clients that have reported healthy=true

          false — only clients that have reported healthy=false

          unknown — only clients that have never reported component health (null health)


          Null health is treated as a distinct unknown state, not as unhealthy.'
        schema:
          items:
            enum:
            - 'true'
            - 'false'
            - unknown
            type: string
          maxItems: 10
          type: array
      - name: connection_health
        in: query
        schema:
          items:
            enum:
            - active
            - inactive
            type: string
          maxItems: 10
          type: array
      - name: filter
        in: query
        description: 'Filter by client metadata attribute. Repeat to apply multiple filters. Different keys = AND logic; same key with multiple exact or prefix values = OR logic.

          Supported value tokens:


          key:value — exact match (e.g. env:prod)

          key:value* — prefix match (e.g. host.name:prod-*)

          key:value\* — exact match for a value ending in a literal * (e.g. env:prod\*)

          key:* — key exists with a non-empty value

          key:!* — key is missing or has an empty value


          Limits: at most 10 filters per request.

          Mixing exact, prefix, key:*, or key:!* operators on the same key returns 400.'
        schema:
          items:
            pattern: ^[^:]+:.*$
            type: string
          maxItems: 10
          type: array
      - name: sort_key
        in: query
        description: Key to sort by. Accepts a metadata key (e.g. host.name) or a system column (instance_uid, healthy). Only one sort_key is accepted per request. Clients missing the sort value, or reporting an empty metadata value, are sorted last.
        schema:
          minLength: 1
          type: string
      - name: sort_dir
        in: query
        description: Sort direction for sort_key. Requires sort_key. Defaults to asc when sort_key is present.
        schema:
          default: asc
          enum:
          - asc
          - desc
          type: string
      responses:
        '200':
          description: HTTP 200 response
          content:
            application/json:
              schema:
                properties:
                  clients:
                    items:
                      properties:
                        connection_health:
                          enum:
                          - active
                          - inactive
                          example: active
                          type: string
                          description: Derived client connection health based on the last confirmed heartbeat. Dead clients outside the liveness window are excluded from client APIs.
                        created_at:
                          example: '2024-01-15T10:30:00Z'
                          format: date-time
                          type: string
                          description: Timestamp when client was first registered
                        health:
                          properties:
                            component_health_map:
                              additionalProperties:
                                example:
                                  component_health_map:
                                    receiver:
                                      healthy: false
                                      last_error: receiver-error
                                      status: failing
                                      status_time_unix_nano: '33'
                                  healthy: true
                                  last_error: top-level-error
                                  start_time_unix_nano: '11'
                                  status: degraded
                                  status_time_unix_nano: '22'
                                properties:
                                  component_health_map:
                                    additionalProperties:
                                      example:
                                        component_health_map:
                                          receiver:
                                            healthy: false
                                            last_error: receiver-error
                                            status: failing
                                            status_time_unix_nano: '33'
                                        healthy: true
                                        last_error: top-level-error
                                        start_time_unix_nano: '11'
                                        status: degraded
                                        status_time_unix_nano: '22'
                                      properties:
                                        component_health_map:
                                          additionalProperties:
                                            example:
                                              component_health_map:
                                                receiver:
                                                  healthy: false
                                                  last_error: receiver-error
                                                  status: failing
                                                  status_time_unix_nano: '33'
                                              healthy: true
                                              last_error: top-level-error
                                              start_time_unix_nano: '11'
                                              status: degraded
                                              status_time_unix_nano: '22'
                                            properties:
                                              component_health_map:
                                                additionalProperties:
                                                  example:
                                                    component_health_map:
                                                      receiver:
                                                        healthy: false
                                                        last_error: receiver-error
                                                        status: failing
                                                        status_time_unix_nano: '33'
                                                    healthy: true
                                                    last_error: top-level-error
                                                    start_time_unix_nano: '11'
                                                    status: degraded
                                                    status_time_unix_nano: '22'
                                                  properties:
                                                    component_health_map:
                                                      additionalProperties:
                                                        example:
                                                          component_health_map:
                                                            receiver:
                                                              healthy: false
                                                              last_error: receiver-error
                                                              status: failing
                                                              status_time_unix_nano: '33'
                                                          healthy: true
                                                          last_error: top-level-error
                                                          start_time_unix_nano: '11'
                                                          status: degraded
                                                          status_time_unix_nano: '22'
                                                        properties:
                                                          component_health_map:
                                                            additionalProperties:
                                                              example:
                                                                component_health_map:
                                                                  receiver:
                                                                    healthy: false
                                                                    last_error: receiver-error
                                                                    status: failing
                                                                    status_time_unix_nano: '33'
                                                                healthy: true
                                                                last_error: top-level-error
                                                                start_time_unix_nano: '11'
                                                                status: degraded
                                                                status_time_unix_nano: '22'
                                                              properties:
                                                                component_health_map:
                                                                  additionalProperties:
                                                                    example:
                                                                      component_health_map:
                                                                        receiver:
                                                                          healthy: false
                                                                          last_error: receiver-error
                                                                          status: failing
                                                                          status_time_unix_nano: '33'
                                                                      healthy: true
                                                                      last_error: top-level-error
                                                                      start_time_unix_nano: '11'
                                                                      status: degraded
                                                                      status_time_unix_nano: '22'
                                                                    properties:
                                                                      component_health_map:
                                                                        additionalProperties:
                                                                          example:
                                                                            component_health_map: null
                                                                            healthy: null
                                                                            last_error: null
                                                                            start_time_unix_nano: null
                                                                            status: null
                                                                            status_time_unix_nano: null
                                                                          properties:
                                                                            component_health_map: null
                                                                            healthy: null
                                                                            last_error: null
                                                                            start_time_unix_nano: null
                                                                            status: null
                                                                            status_time_unix_nano: null
                                                                          type: object
                                                                          title: ComponentHealth
                                                                        example:
                                                                          receiver:
                                                                            healthy: null
                                                                            last_error: null
                                                                            status: null
                                                                            status_time_unix_nano: null
                                                                        type: object
                                                                        description: Map of nested component name to its health object. Values use the same recursive ComponentHealth schema.
                                                                      healthy:
                                                                        example: true
                                                                        type: boolean
                                                                        description: Set to true if the component is up and healthy
                                                                      last_error:
                                                                        example: 'Failed to connect to backend: connection timeout'
                                                                        type: string
                                                                        description: Human-readable error message if the component is in erroneous state
                                                                      start_time_unix_nano:
                                                                        example: '1705323000000000000'
                                                                        format: int64
                                                                        type: string
                                                                        description: Timestamp since the component is up, UNIX Epoch time in nanoseconds.
                                                                      status:
                                                                        example: running
                                                                        type: string
                                                                        description: Component status represented as a string.
                                                                      status_time_unix_nano:
                                                                        example: '1706447355000000000'
                                                                        format: int64
                                                                        type: string
                                                                        description: The time when the component status was observed, UNIX Epoch time in nanoseconds.
                                                                    type: object
                                                                    title: ComponentHealth
                                                                    description: The health of the agent and any nested sub-components. The component_health_map can be nested to represent multi-level component hierarchies.
                                                                  example:
                                                                    receiver:
                                                                      healthy: false
                                                                      last_error: receiver-error
                                                                      status: failing
                                                                      status_time_unix_nano: '33'
                                                                  type: object
                                                                  description: Map of nested component name to its health object. Values use the same recursive ComponentHealth schema.
                                                                healthy:
                                                                  example: true
                                                                  type: boolean
                                                                  description: Set to true if the component is up and healthy
                                                                last_error:
                                                                  example: 'Failed to connect to backend: connection timeout'
                                                                  type: string
                                                                  description: Human-readable error message if the component is in erroneous state
                                                                start_time_unix_nano:
                                                                  example: '1705323000000000000'
                                                                  format: int64
                                                                  type: string
                                                                  description: Timestamp since the component is up, UNIX Epoch time in nanoseconds.
                                                                status:
                                                                  example: running
                                                                  type: string
                                                                  description: Component status represented as a string.
                                                                status_time_unix_nano:
                                                                  example: '1706447355000000000'
                                                                  format: int64
                                                                  type: string
                                                                  description: The time when the component status was observed, UNIX Epoch time in nanoseconds.
                                                              type: object
                                                              title: ComponentHealth
                                                              description: The health of the agent and any nested sub-components. The component_health_map can be nested to represent multi-level component hierarchies.
                                                            example:
                                                              receiver:
                                                                healthy: false
                                                                last_error: receiver-error
                                                                status: failing
                                                                status_time_unix_nano: '33'
                                                            type: object
                                                            description: Map of nested component name to its health object. Values use the same recursive ComponentHealth schema.
                                                          healthy:
                                                            example: true
                                                            type: boolean
                                                            description: Set to true if the component is up and healthy
                                                          last_error:
                                                            example: 'Failed to connect to backend: connection timeout'
                                                            type: string
                                                            description: Human-readable error message if the component is in erroneous state
                                                          start_time_unix_nano:
                                                            example: '1705323000000000000'
                                                            format: int64
                                                            type: string
                                                            description: Timestamp since the component is up, UNIX Epoch time in nanoseconds.
                                                          status:
                                                            example: running
                                                            type: string
                                                            description: Component status represented as a string.
                                                          status_time_unix_nano:
                                                            example: '1706447355000000000'
                                                            format: int64
                                                            type: string
                                                            description: The time when the component status was observed, UNIX Epoch time in nanoseconds.
                                                        type: object
                                                        title: ComponentHealth
                                                        description: The health of the agent and any nested sub-components. The component_health_map can be nested to represent multi-level component hierarchies.
                                                      example:
                                                        receiver:
                                                          healthy: false
                                                          last_error: receiver-error
                                                          status: failing
                                                          status_time_unix_nano: '33'
                                                      type: object
                                                      description: Map of nested component name to its health object. Values use the same recursive ComponentHealth schema.
                                                    healthy:
                                                      example: true
                                                      type: boolean
                                                      description: Set to true if the component is up and healthy
                                                    last_error:
                                                      example: 'Failed to connect to backend: connection timeout'
                                                      type: string
                                                      description: Human-readable error message if the component is in erroneous state
                                                    start_time_unix_nano:
                                                      example: '1705323000000000000'
                                                      format: int64
                                                      type: string
                                                      description: Timestamp since the component is up, UNIX Epoch time in nanoseconds.
                                                    status:
                                                      example: running
                                                      type: string
                                                      description: Component status represented as a string.
                                                    status_time_unix_nano:
                                                      example: '1706447355000000000'
                                                      format: int64
                                                      type: string
                                                      description: The time when the component status was observed, UNIX Epoch time in nanoseconds.
                                                  type: object
                                                  title: ComponentHealth
                                                  description: The health of the agent and any nested sub-components. The component_health_map can be nested to represent multi-level component hierarchies.
                                                example:
                                                  receiver:
                                                    healthy: false
                                                    last_error: receiver-error
                                                    status: failing
                                                    status_time_unix_nano: '33'
                                                type: object
                                                description: Map of nested component name to its health object. Values use the same recursive ComponentHealth schema.
                                              healthy:
                                                example: true
                                                type: boolean
                                                description: Set to true if the component is up and healthy
                                              last_error:
                                                example: 'Failed to connect to backend: connection timeout'
                                                type: string
                                                description: Human-readable error message if the component is in erroneous state
                                              start_time_unix_nano:
                                                example: '1705323000000000000'
                                                format: int64
                                                type: string
                                                description: Timestamp since the component is up, UNIX Epoch time in nanoseconds.
                                              status:
                                                example: running
                                                type: string
                                                description: Component status represented as a string.
                                              status_time_unix_nano:
                                                example: '1706447355000000000'
                                                format: int64
                                                type: string
                                                description: The time when the component status was observed, UNIX Epoch time in nanoseconds.
                                            type: object
                                            title: ComponentHealth
                                            description: The health of the agent and any nested sub-components. The component_health_map can be nested to represent multi-level component hierarchies.
                                          example:
                                            receiver:
                                              healthy: false
                                              last_error: receiver-error
                                              status: failing
                                              status_time_unix_nano: '33'
                                          type: object
                                          description: Map of nested component name to its health object. Values use the same recursive ComponentHealth schema.
                                        healthy:
                                          example: true
                                          type: boolean
                                          description: Set to true if the component is up and healthy
                                        last_error:
                                          example: 'Failed to connect to backend: connection timeout'
                                          type: string
                                          description: Human-readable error message if the component is in erroneous state
                                        start_time_unix_nano:
                                          example: '1705323000000000000'
                                          format: int64
                                          type: string
                                          description: Timestamp since the component is up, UNIX Epoch time in nanoseconds.
                 

# --- truncated at 32 KB (129 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/splunk-observability/refs/heads/main/openapi/splunk-observability-client-inventory-api-openapi.yml