Public observability API

The WOCU-Monitoring public observability API enables external systems and tools to access observability data from a Kingdom, including metrics, monitoring events, detected anomalies, behaviour predictions (forecasting), hardware status and network traffic.

There are 20 read-only operations under /api/v1/observability/realm/<realm>/.

Key features

Integrating WOCU-Monitoring with other tools: this allows you to feed observability data into dashboards, API managers or external observability platforms without having to access the interface.

Automate queries: avoid manually collecting, tab by tab, the data displayed in the Observability dashboards.

Integration without blind testing: with the full reference, the person carrying out the integration knows in advance which fields they will receive and how to handle each error.

How does it work?

Where does it get its information from?

From the data that WOCU-Monitoring already stores for the realm. Anomalies, forecasts and hardware status are retrieved from the realm’s Elasticsearch; metrics and events, from its monitoring store; and network traffic, from the flow data.

What WOCU-Monitoring processes

Check that the user has access to the realm, validate the parameters and calculate the result: for example, count the hosts with anomalies or group traffic by port.

What result does it produce?

A JSON response; metrics and events can also be requested in OpenTelemetry (OTLP) format.

Update

Each response is calculated at the time of the request. The panels indicate the time to which it corresponds in the as_of field.

Subdivisions

Anomalies and forecasting depend on the machine learning work carried out by Elastic in the realm. Network traffic depends on the realm having flow collection enabled.

How do you use it?

1. Disponer de un usuario de WOCU-Monitoring con acceso al reino que se quiere consultar.

2. Elegir cómo autenticarse: usuario y contraseña (HTTP Basic), token (Authorization: Token <clave>) o JWT (Authorization: Bearer <JWT>).

3. Consultar la referencia y elegir la operación: en la página Documentación API pública del manual o en el Swagger de la instalación (/api-docs/).

4. Lanzar una petición GET a /api/v1/observability/realm/<realm>/<operación>/ con los parámetros necesarios.

5. Leer la respuesta. Si la operación pagina, repetir la petición con el next_offset o el next_cursor recibido hasta que no queden más datos.

Example: hosts with anomalies in the last 30 days

Request:

curl -u <usuario>:<contraseña> \
    "<dirección-del-aggregator>/api/v1/observability/realm/<realm>/anomalies/summary/"

Answer:

{
    "realm": "demo-realm",
    "as_of": "2026-01-31T12:00:00Z",
    "time_from": "2026-01-01T12:00:00Z",
    "time_to": "2026-01-31T12:00:00Z",
    "hosts": 12,
    "window_days": 30,
    "exact": true
}

Available options

Operations

Option

Description

metrics/

Returns the metric series for the hosts in the realm, using the requested aggregation function (avg, min, max, sum or count) and interval. It only returns metrics from the installation’s allowed list.

events/

Returns monitoring events (alerts, notifications, flapping) with a fixed set of fields and a standardised severity rating.

hardware-health/summary/

This indicates how many hosts have hardware in a critical, warning, unknown, insufficient data or monitoring interrupted state.

anomalies/… (6 operations)

This section describes the hosts with anomalies detected by machine learning: summary, weekly trend, breakdown by severity, daily trend, breakdown by resource (CPU or memory) and a list of hosts.

forecasting/… (4 operations)

They provide a 24-hour forecast for CPU and memory: available instances, a summary of the hosts that will exceed their thresholds, a host series and a list of metrics.

network-traffic/… (7 operations)

They measure the volume of traffic observed in the data flows: summary, main service ports, protocols, trends, changes compared with the previous period, data quality and main destinations.

Parameters

Option

Description

time_from, time_to

They specify the range of metrics and events, in the format DD/MM/YYYY HH:MM:SS and in the local time of the installation. If these are not provided, the most recent time is used.

from, to

The range of panels that support this is restricted to ISO 8601 (UTC if no offset is specified) or epoch milliseconds. ‘from’ is included and ‘to’ is not.

By default, the period is 30 days for anomalies and network traffic, and 24 hours for the forecasting series.

as_of

Set the time to which the response refers in the summary, the anomaly trend and the forecasting. By default, this is the time of the request.

size, offset

The metrics are displayed per page: how many hosts each page contains (10 by default) and which one to proceed from.

For events, ‘size’ is the maximum number of events returned.

limit, cursor

They paginate the list of hosts with anomalies and the forecasting runs (100 rows by default, 1,000 at most).

In the other lists, limit specifies how many main rows to return.

sort

Sort events by date or status. By default, the most recent appear first.

format

For metrics and events only: json (by default), otlp or otlp-ndjson to receive the data in OpenTelemetry format.

monitoring_gap_minutes

In the hardware status, this sets the number of minutes without samples after which a host is considered to be down: 0, 15, 30, 60 or 120 (default: 15).

transport, service_port, exporter_address

They restrict network traffic to a single protocol (tcp or udp), a single port or a maximum of 20 senders.

Result

Where to find it

In the response to each request, in JSON.

What information is displayed?

The reference lists, for each operation, all the fields along with their type and meaning, and an example. The panels share four header fields: realm, as_of, time_from and time_to.

How to interpret it

The code 200 returns the data.

The rest explains the reason for the failure:

Code

Meaning

400

One parameter is invalid; the answer states which one.

401

The credentials are invalid.

403

The user does not have access to the realm.

404

The domain or resource requested does not exist.

429

The client has exceeded their request limit.

502, 504

The data query failed or the time limit has expired. The data is unknown, not empty.

What to do next

Continue pagination if there is any data remaining, or load the result into the external tool.

Considerations and limitations

Read-only

All operations are GET and do not modify anything.

Permits

The user requires access to the realm. If the installation uses path-based access rules, the user must also be granted access to that path.

Data in Elasticsearch

Anomalies, forecasting and hardware status mean that the kingdom must store its data in Elasticsearch; otherwise, it returns a ‘400’ response.

Flow collection

Network traffic requires the server to collect flow data; otherwise, it returns a ‘404’ response.

Maximum range

A query covers a maximum of 31 days for metrics, events and network traffic. For metrics and events, this maximum is a configuration setting.

Scope of forecasting

It covers six CPU and memory metrics, with a 24-hour time horizon broken down into 15-minute intervals.

Request limits

These apply only to customers who have a limit record.

Traffic volume

These are bytes observed in the data streams, without normalising the sampling or removing duplicates.

Field names

Some response fields have Spanish names (affected, unknown, Device, Level); the reference explains them in English.

Error format

It is not consistent: ‘401’ and ‘403’ return a text message, whilst the rest return JSON.