LumeScope SuperNodes API reference

The LumeScope SuperNodes API aggregates hardware telemetry, payment statistics, availability probes, and version compatibility data for every SuperNode registered on the Lumera network. LumeScope probes each SuperNode on a configurable interval and stores the results. Your application can query current status, rank individual nodes by resources, and identify nodes that are temporarily unreachable. You never need direct access to an operator’s machine.

All SuperNodes API endpoints are read-only and require no authentication. The base URL for mainnet is https://api.lumera.io. Substitute https://api.testnet.lumera.io for testnet.

GET /v1/supernodes/metrics

Returns hardware and network metrics for all SuperNodes. Use query parameters to filter by status, version, or failure threshold, and to paginate large result sets.

Query parameters

string

Filter by probe status. Common values are available and unavailable.

string

Filter by the node’s on-chain validator state.

string

Filter to nodes running a specific software version string.

integer

Return only nodes whose consecutive probe failure count is at or above this threshold. Useful for identifying persistently offline nodes.

integer

default:"50"

Maximum number of SuperNodes to return per page.

string

Opaque pagination cursor returned by the previous response. Pass this value to retrieve the next page.

Example request

curl https://api.lumera.io/v1/supernodes/metrics

curl "https://api.lumera.io/v1/supernodes/metrics?status=available&limit=10"

Example response

{
  "supernodes": [
    {
      "id": "lumera15abc...",
      "ip": "192.0.2.10",
      "status": "available",
      "rank": 1,
      "version": "1.2.0",
      "registered_services": ["cascade", "sense"],
      "peer_count": 42,
      "cpu_cores": 16,
      "cpu_usage_percent": 23.4,
      "memory_total_gb": 64,
      "memory_used_gb": 18.2,
      "storage_total_gb": 2000,
      "storage_used_gb": 450,
      "failed_probe_counter": 0
    }
  ],
  "cursor": "eyJpZCI6Imx1bWVyYTE1YWJjIn0="
}

Response fields

array

Array of SuperNode metric objects.

Show SuperNode metric fields

string

Bech32 operator address of the SuperNode.

string

Public IP address of the node.

string

The probe status, either available or unavailable.

integer

Relative ranking among all SuperNodes (lower is better).

string

Software version string reported by the node.

array

List of services the node has registered, e.g. cascade, sense.

integer

Number of active peer connections at the time of the last probe.

integer

Total CPU core count on the node.

number

CPU utilization percentage at the time of the last probe.

number

Total installed RAM in gigabytes.

number

RAM in use at the time of the last probe.

number

Total storage capacity in gigabytes.

number

Storage consumed at the time of the last probe.

integer

Number of consecutive failed probes since the last successful contact.

string

Pagination cursor. Pass this as the cursor query parameter to retrieve the next page. Absent when there are no more results.

GET /v1/supernodes/{id}/metrics

Returns the current hardware and network metrics for a single SuperNode identified by its operator address.

Path parameters

string

required

The Bech32 operator address of the SuperNode (e.g. lumera15abc...).

Example request

curl https://api.lumera.io/v1/supernodes/lumera15abc.../metrics

Example response

{
  "id": "lumera15abc...",
  "ip": "192.0.2.10",
  "status": "available",
  "rank": 1,
  "version": "1.2.0",
  "registered_services": ["cascade", "sense"],
  "peer_count": 42,
  "cpu_cores": 16,
  "cpu_usage_percent": 23.4,
  "memory_total_gb": 64,
  "memory_used_gb": 18.2,
  "storage_total_gb": 2000,
  "storage_used_gb": 450,
  "failed_probe_counter": 0
}

The response object uses the same field schema as the individual entries in GET /v1/supernodes/metrics.

GET /v1/supernodes/{id}/paymentInfo

Returns payment statistics broken down by denomination for a specific SuperNode. Use this endpoint to audit reward distribution or inspect historical payment totals.

Path parameters

string

required

The Bech32 operator address of the SuperNode.

Example request

curl https://api.lumera.io/v1/supernodes/lumera15abc.../paymentInfo

Example response

{
  "id": "lumera15abc...",
  "payments": [
    {
      "denom": "ulume",
      "total_amount": "1500000000",
      "payment_count": 3200
    }
  ]
}

Response fields

string

Bech32 operator address of the SuperNode.

array

List of payment totals, one entry per denomination.

Show Payment entry fields

string

Token denomination (e.g. ulume).

string

Cumulative payment amount in the smallest unit of the denomination.

integer

Number of individual payment transactions included in this total.

GET /v1/supernodes/stats

Returns aggregated hardware statistics across all SuperNodes. You get network-wide totals and averages for CPU, memory, and storage. Use this endpoint for capacity-planning dashboards and fleet health snapshots.

Example request

curl https://api.lumera.io/v1/supernodes/stats

Example response

{
  "total_supernodes": 120,
  "available_count": 115,
  "unavailable_count": 5,
  "avg_cpu_usage_percent": 21.8,
  "total_storage_tb": 240,
  "total_memory_gb": 7680
}

Response fields

integer

Total number of SuperNodes tracked by LumeScope.

integer

Number of SuperNodes with a passing probe status.

integer

Number of SuperNodes that failed their most recent probe.

number

Fleet-wide average CPU utilization percentage.

number

Combined storage capacity across all available SuperNodes, in terabytes.

number

Combined RAM across all available SuperNodes, in gigabytes.

GET /v1/supernodes/action-stats

Returns per-SuperNode action statistics. The response shows how many Cascade and Sense actions each node has participated in. Use this endpoint to identify the most active nodes or detect imbalanced workload distribution.

Example request

curl https://api.lumera.io/v1/supernodes/action-stats

Example response

{
  "supernodes": [
    {
      "id": "lumera15abc...",
      "cascade_count": 420,
      "sense_count": 180,
      "total_count": 600
    }
  ]
}

Response fields

array

Array of per-SuperNode action count objects.

Show Action stats fields

string

Bech32 operator address of the SuperNode.

integer

Number of Cascade actions this node has been involved in.

integer

Number of Sense actions this node has been involved in.

integer

Combined Cascade and Sense action count.

GET /v1/supernodes/unavailable

Returns the list of SuperNodes whose most recent probe reported an unavailable status. This endpoint is the quickest way to triage connectivity or operator issues without filtering the full metrics list.

Query parameters

string

Filter by on-chain validator state, e.g. active, jailed.

Example request

curl https://api.lumera.io/v1/supernodes/unavailable

Example response

{
  "supernodes": [
    {
      "id": "lumera1xyz...",
      "ip": "192.0.2.99",
      "failed_probe_counter": 12,
      "last_seen_at": "2024-01-14T08:00:00Z"
    }
  ]
}

Response fields

array

Array of unavailable SuperNode objects.

Show Unavailable supernode fields

string

Bech32 operator address.

string

Public IP address of the node.

integer

Consecutive probe failures since the node was last reachable.

string

RFC 3339 timestamp of the last successful probe.

POST /v1/supernodes/sync

Triggers an immediate, out-of-schedule sync and probe of all SuperNodes. Under normal operation LumeScope syncs automatically on the configured SUPERNODES_SYNC_INTERVAL. Use this endpoint when you need fresh data immediately after an operator change or network event.

Manual sync is only available when the LumeScope instance is configured to allow it. On the public mainnet and testnet endpoints this endpoint may return 403 Forbidden.

Example request

curl -X POST https://api.lumera.io/v1/supernodes/sync

Example response

{
  "status": "sync triggered",
  "triggered_at": "2024-01-15T11:00:00Z"
}

Response fields

string

Confirmation message indicating the sync was accepted.

string

RFC 3339 timestamp at which the sync was initiated.

GET /v1/version/matrix

Returns the version compatibility matrix for SuperNode software, implementing a partial view of the Lumera Enhancement Proposal 2 (LEP2) versioning scheme. Use this endpoint to determine which node versions are compatible with the current network state.

Example request

curl https://api.lumera.io/v1/version/matrix

Example response

{
  "matrix": [
    {
      "node_version": "1.2.0",
      "compatible_versions": ["1.1.0", "1.2.0"],
      "deprecated": false
    },
    {
      "node_version": "1.1.0",
      "compatible_versions": ["1.1.0"],
      "deprecated": true
    }
  ],
  "current_recommended": "1.2.0"
}

Response fields

array

Array of version compatibility entries.

Show Version matrix entry fields

string

The SuperNode software version this entry describes.

array

List of other software versions that this version can inter-operate with.

boolean

true if this version is end-of-life and operators should upgrade.

string

The latest recommended SuperNode software version according to the compatibility matrix.

Poll GET /v1/supernodes/unavailable on a schedule and alert your team when failed_probe_counter exceeds a threshold. This gives you early warning of persistent connectivity issues before they affect action processing.

REST API

RPC

gRPC API

Libraries and tools

LumeScope SuperNodes API reference

GET /v1/supernodes/metrics

Query parameters

Example request

Example response

Response fields

GET /v1/supernodes/{id}/metrics

Path parameters

Example request

Example response

GET /v1/supernodes/{id}/paymentInfo

Path parameters

Example request

Example response

Response fields

GET /v1/supernodes/stats

Example request

Example response

Response fields

GET /v1/supernodes/action-stats

Example request

Example response

Response fields

GET /v1/supernodes/unavailable

Query parameters

Example request

Example response

Response fields

POST /v1/supernodes/sync

Example request

Example response

Response fields

GET /v1/version/matrix

Example request

Example response

Response fields

​GET /v1/supernodes/metrics

​Query parameters

​Example request

​Example response

​Response fields

​GET /v1/supernodes/{id}/metrics

​Path parameters

​Example request

​Example response

​GET /v1/supernodes/{id}/paymentInfo

​Path parameters

​Example request

​Example response

​Response fields

​GET /v1/supernodes/stats

​Example request

​Example response

​Response fields

​GET /v1/supernodes/action-stats

​Example request

​Example response

​Response fields

​GET /v1/supernodes/unavailable

​Query parameters

​Example request

​Example response

​Response fields

​POST /v1/supernodes/sync

​Example request

​Example response

​Response fields

​GET /v1/version/matrix

​Example request

​Example response

​Response fields

GET /v1/supernodes/metrics

Query parameters

Example request

Example response

Response fields

GET /v1/supernodes/{id}/metrics

Path parameters

Example request

Example response

GET /v1/supernodes/{id}/paymentInfo

Path parameters

Example request

Example response

Response fields

GET /v1/supernodes/stats

Example request

Example response

Response fields

GET /v1/supernodes/action-stats

Example request

Example response

Response fields

GET /v1/supernodes/unavailable

Query parameters

Example request

Example response

Response fields

POST /v1/supernodes/sync

Example request

Example response

Response fields

GET /v1/version/matrix

Example request

Example response

Response fields