Manage OpenTelemetry collectors and agents using APIs

How to use the Client Inventory API to monitor, troubleshoot, and audit your fleet.

Use the Client Inventory API to monitor, troubleshoot, and audit your fleet.

The examples in this topic use the us0 realm. Replace us0 in each URL with your Splunk Observability Cloud realm. Send a Splunk Observability Cloud access token in the X-SF-TOKEN header with every request.

Supported clients

  • Splunk distribution of OpenTelemetry Collector (Agent and Gateway modes) 0.126.0 and later.

  • Splunk distribution of OpenTelemetry Java agent 2.27.0 or later

  • Splunk Distribution of OpenTelemetry Node.js agent 4.8.0 or later

Monitor the fleet health

The List clients API includes health data by default. To retrieve client inventory without health data, set the include_health query parameter to false. This is useful for analytical queries or large-scale inventory reports where health details aren't needed.

The following request retrieves clients whose region metadata value is us-east and excludes health data from the response:

CODE 
GET https://api.us0.observability.splunkcloud.com/v2/fm-service/v1/clients?filter=region%3Aus-east&include_health=false
X-SF-TOKEN: <access-token>

To retrieve the current record for one client, including its metadata, timestamps, and health information when available, use the Get client by ID API:

JSON 
GET https://api.us0.observability.splunkcloud.com/v2/fm-service/v1/clients/{id}
X-SF-TOKEN: <access-token>

Replace {id} with the client instance UID. The Get client by ID API doesn't support the `include_health` query parameter.

Troubleshoot the agent configuration

If an agent isn't performing as expected, retrieve its effective configuration to compare it against the target state. Set stringify to true to include UTF-8 string content for human-readable formats such as YAML or JSON.
JSON 
GET https://api.us0.observability.splunkcloud.com/v2/fm-service/v1/clients/{id}/config?stringify=true
X-SF-TOKEN: <access-token>

Replace {id} with the client instance UID.

Audit the fleet configuration

For compliance or troubleshooting across a cluster, use the batch endpoint to retrieve effective configurations for multiple clients in a single request. The response maps each found client ID to its configuration and lists missing client IDs in notFound.

JSON 
POST https://api.us0.observability.splunkcloud.com/v2/fm-service/v1/clients/configs:batch
X-SF-TOKEN: <access-token>
Content-Type: application/json

{
  "clientIds": [
    "550e8400-e29b-41d4-a716-446655440000",
    "550e8400-e29b-41d4-a716-446655440001"
  ],
  "stringify": true
}

API reference

See the API specification for more information: https://dev.splunk.com/observability/reference/api/client_inventory/latest/#api-overview