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_offield.
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
GETa/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_offseto elnext_cursorrecibido 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 |
|---|---|
|
Returns the metric series for the hosts in the realm, using the requested aggregation function ( |
|
Returns monitoring events (alerts, notifications, flapping) with a fixed set of fields and a standardised severity rating. |
|
This indicates how many hosts have hardware in a critical, warning, unknown, insufficient data or monitoring interrupted state. |
|
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. |
|
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. |
|
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 |
|---|---|
|
They specify the range of metrics and events, in the format |
|
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. |
|
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. |
|
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. |
|
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 events by date or status. By default, the most recent appear first. |
|
For metrics and events only: |
|
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). |
|
They restrict network traffic to a single protocol ( |
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_fromandtime_to.
How to interpret it
The code
200returns the data.The rest explains the reason for the failure:
Code |
Meaning |
|---|---|
|
One parameter is invalid; the answer states which one. |
|
The credentials are invalid. |
|
The user does not have access to the realm. |
|
The domain or resource requested does not exist. |
|
The client has exceeded their request limit. |
|
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
GETand 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.