1.7. API Endpoints - Monitoring and Analytics

1.7.1. Alerts

1.7.1.1. GET /alerts/

Description

Retrieves a list of active, non-muted alerts from the Ngenea Hub system.

This endpoint is primarily used by the Hub UI to populate both Global and Site-specific alert dashboards. The API supports filtering by multiple parameters such as name, site, node, severity, and more.

Note

  • All parameters in the Swagger UI for this endpoint are optional.

  • The response will be filtered based on the parameters you provide (e.g., filtering by name, site, or severity).

  • If no parameters are specified, the API will return all active and non-muted alerts by default.

Request Parameters

Name

Type

Location

Description

name

string

query

Filter alerts by name (e.g., SiteHealth)

site

string

query

Filter alerts by site name

node

string

query

Filter alerts by node name

severity

string

query

Filter alerts by severity (INFO, WARNING, CRITICAL)

summary

string

query

Filter alerts by summary text

timestamp

string

query

Filter alerts by timestamp (ISO 8601 format)

suppressed

string

query

Filter alerts by suppression status

Example Request

curl -X 'GET' \
  'http://your-hub-address:8000/api/alerts/?name=SiteHealth' \
  -H 'accept: application/json' \
  -H 'Authorization: Api-Key your-api-key'

Successful Response

HTTP Status Code: 200 OK

Content-Type: application/json

Example Response

[
  {
    "id": 99,
    "site": "testexample",
    "name": "SiteHealth",
    "node": null,
    "queue": null,
    "created": "2025-07-03T14:33:00.031598Z",
    "timestamp": "2025-08-07T12:16:00.018308Z",
    "severity": "INFO",
    "summary": "No workers are joined",
    "suppressed": false
  }
]

Response Fields

Field

Type

Description

id

integer

Unique ID of the alert

site

string

Name of the site where the alert occurred

name

string

Alert name/type (e.g., SiteHealth)

node

string

Node name if applicable

queue

string

Queue name if applicable

created

string

ISO timestamp when alert was created

timestamp

string

ISO timestamp of the most recent alert event

severity

string

Alert severity (INFO, WARNING, CRITICAL)

summary

string

Short summary of the alert

suppressed

boolean

Whether the alert is currently suppressed

1.7.1.2. GET /alerts/{id}/

Description

Fetch detailed information about a specific alert using its unique ID. This endpoint returns the full alert object, including metadata such as severity, timestamps, and associated site or node.

Used by the Hub system to display detailed alert information in dashboards or drill-down views.

Request Parameters

Name

Type

Location

Description

id

integer

path

A unique integer identifying the alert. (Required)

Example Request

curl -X 'GET' \
  'http://your-hub-address:8000/api/alerts/99/' \
  -H 'accept: application/json' \
  -H 'Authorization: Api-Key your-api-key'

Successful Response

HTTP Status Code: 200 OK

Content-Type: application/json

Example Response

{
  "id": 99,
  "site": "testexample",
  "name": "SiteHealth",
  "node": null,
  "queue": null,
  "created": "2025-07-03T14:33:00.031598Z",
  "timestamp": "2025-08-07T12:28:00.014935Z",
  "severity": "INFO",
  "summary": "No workers are joined",
  "suppressed": false
}

Response Fields

Please refer to the response feilds under GET /alerts/.

1.7.2. Health

1.7.2.1. GET /health/

Description

The GET /health/ endpoint provides a real-time overview of the health status of the Ngenea Hub and all connected infrastructure components.

This endpoint is used to monitor:

  • The health of the Hub service itself

  • All registered sites

  • The nodes (servers/machines) within each site

  • Any associated queues

The system reports health using the following states:

  • ok: All nodes in the site are functioning normally

  • warning: Some nodes are offline or unresponsive

  • critical: An entire site is offline (no working nodes)

By querying this endpoint, administrators can quickly assess which parts of the infrastructure are healthy and identify potential issues at the site or node level. This is useful for operational monitoring, alerting, and overall system visibility.

Request Parameters

This endpoint does not require any parameters. Simply calling the endpoint returns the health status of the Hub and all registered Sites.

Example Request

curl -X 'GET' \
  'http://your-hub-address:8000/api/health/' \
  -H 'accept: application/json' \
  -H 'Authorization: Api-Key your-api-key'

Successful Response

HTTP Status Code: 200 OK

Content-Type: application/json

Example Response

{
  "overall_health": "ok",
  "hub_status": {
    "health": "ok"
  },
  "site_status": [
    {
      "site": "Site 1",
      "health": "ok",
      "nodes": [
        {
          "name": "Site 1",
          "health": "ok",
          "online": true,
          "has_default_queue": true,
          "last_heartbeat": "2025-08-07T13:34:23.276099+00:00",
          "worker_version": "2.6.0",
          "ngenea_version": "1.31.0",
          "analytics_version": "2.7.1",
          "search_version": "1.2.0"
        }
      ],
      "queues": [
        {
          "name": "default",
          "health": "ok",
          "online": true,
          "last_heartbeat": "2025-08-07T13:34:23.276099+00:00"
        }
      ]
    },
    {
      "site": "Site 2",
      "health": "ok",
      "nodes": [
        {
          "name": "Site 1",
          "health": "ok",
          "online": true,
          "has_default_queue": true,
          "last_heartbeat": "2025-08-07T13:34:24.781445+00:00",
          "worker_version": "2.6.0",
          "ngenea_version": "1.31.0",
          "analytics_version": "2.7.1",
          "search_version": "1.2.0"
        },
        {
          "name": "sitetest",
          "health": "ok",
          "online": true,
          "has_default_queue": true,
          "last_heartbeat": "2025-07-01T10:54:54.269000+00:00",
          "version_details": "Could not retrieve version information for example@sitetest"
        }
      ],
      "queues": [
        {
          "name": "default",
          "health": "ok",
          "online": true,
          "last_heartbeat": "2025-08-07T13:34:34.791954+00:00"
        }
      ]
    },
    {
      "site": "testexample",
      "health": "ok",
      "nodes": [],
      "queues": []
    }
  ]
}

Response Fields

Field

Type

Description

overall_health

string

Overall system health status (ok, warning, error, etc.)

hub_status.health

string

Health status of the central Hub component

site_status

array

List of health status entries per site

site_status[].site

string

Name of the site

site_status[].health

string

Health of the site (ok, etc.)

site_status[].nodes

array

List of nodes for that site

site_status[].nodes[].name

string

Node name

site_status[].nodes[].health

string

Health of the node

site_status[].nodes[].online

boolean

Whether the node is online

site_status[].nodes[].has_default_queue

boolean

Whether the node has the default queue

site_status[].nodes[].last_heartbeat

string

Timestamp of last node heartbeat

site_status[].nodes[].worker_version

string

Worker component version (if available)

site_status[].nodes[].ngenea_version

string

Ngenea service version (if available)

site_status[].nodes[].analytics_version

string

Analytics service version

site_status[].nodes[].search_version

string

Search service version

site_status[].nodes[].version_details

string

Additional version info or errors (optional)

site_status[].queues

array

List of queue objects for the site

site_status[].queues[].name

string

Name of the queue

site_status[].queues[].health

string

Health of the queue

site_status[].queues[].online

boolean

Whether the queue is online

site_status[].queues[].last_heartbeat

string

Timestamp of last queue heartbeat

1.7.4. Analytics

1.7.4.1. GET /analytics

Description

The GET /analytics/ endpoint retrieves analytics data related to file storage usage for a specified site and directory path. It provides information such as the total number of files, total bytes used, and per-directory or per-storage pool statistics. The API supports optional parameters like pagination, child directory inclusion, CSV downloads, and customizable timeout or cache settings.

This API is used when there is a need to understand how storage is being utilized within a site. It is particularly useful for analyzing a specific directory or for retrieving detailed data across child directories.

Administrators can call this endpoint periodically or on demand to review current storage metrics.

It is useful for storage monitoring, capacity planning, and troubleshooting. By analyzing file count and storage consumption, teams can optimize storage usage, detect anomalies or growth patterns, and generate reports for internal audits or compliance purposes. The option to export data as CSV makes it convenient for external reporting or integration with other tools.

Request Parameters

Name

Type

Required

Description

site

string

Yes

The name of the site to retrieve analytics for. Minimum length: 1.

path

string

No

The target directory path to analyze. If not provided, analytics will be retrieved for all space roots.

page

integer

No

Page number within the paginated result set. Defaults to 1 if not provided.

page_size

integer

No

Number of results per page. Must be between 20 and 100. Use 0 to disable pagination and retrieve all results. Defaults to 20 if not specified or too low.

children

boolean

No

Whether to include child directories in the response. Default is false.

cache_ttl

integer

No

Optional cache time-to-live for the analytics data (in seconds).

custom_timeout

integer

No

Custom timeout (in seconds) for fetching analytics data.

download

string

No

If set to csv, returns the result as a downloadable CSV file.

Example Request

curl -X GET \
  'http://your-hub-address:8000/api/analytics/?page=1&site=siteB&children=true' \
  -H 'accept: application/json' \
  -H 'Authorization: Api-Key <your-api-key>'

Successful Response

HTTP Status Code: 200 OK

Content-Type: application/json

Example Response

{
  "children": {
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
      {
        "site": "siteB",
        "pools": [
          {
            "name": "sas1",
            "total_used_bytes": 475529216,
            "total_files_count": 532
          },
          {
            "name": "cloud",
            "total_used_bytes": 0,
            "total_files_count": 0
          }
        ],
        "path": "/mmfs1",
        "total_used_bytes": 475529216,
        "total_files_count": 532
      }
    ]
  },
  "site": "siteB",
  "pools": [],
  "path": "",
  "total_used_bytes": null,
  "total_files_count": null
}

Response Fields

Field

Type

Description

children

object

Contains results for child directories (if children=true was set).

children.count

integer

Total number of items returned.

children.results

array

List of objects representing directories under the target path.

site

string

Name of the site queried.

pools

array

List of storage pools (only filled when the path is not specified or children are not included).

path

string

The requested directory path.

total_used_bytes

integer

Total disk usage in bytes for the specified path.

total_files_count

integer

Total number of files under the specified path.