Status API

Node-specific state and consensus metrics

This API provides insight into the inner workings of consensus. The metrics are useful for monitoring node health and setting up alerts.

Enabling the Status API

Enable the status API by appending the http and status module flags to your node's startup command:

sequencer [options] -- http -- status [-- other modules...]

Public Access

The API is served over HTTP on the port configured via ESPRESSO_SEQUENCER_API_PORT. Node operators should ensure this port is reachable from the internet so the Espresso team can monitor overall network health and identify nodes that may need attention.

To verify the API is accessible, replace the URL below with your node's public IP or domain name and run from an external machine:

# Direct access over HTTP (replace 8080 with your ESPRESSO_SEQUENCER_API_PORT):
curl http://203.0.113.10:8080/status/metrics

# If you have a reverse proxy with TLS (recommended for production):
curl https://my-espresso-node.example.com/status/metrics

You should see Prometheus-formatted metrics:

# HELP ...
# TYPE ...
...

The node serves plain HTTP. For production deployments we recommend setting up HTTPS via a reverse proxy.

Monitoring Recommendations

Node Version

The consensus_version metric reports the image tag and git revision your node is running:

consensus_version{desc="20260312",rev="c71063750783484374a5d879da9d320feb32ec80",...} 1

Verify the desc label is at least the latest recommended image tag from the running a mainnet node guide.

Timeouts as Leader

The consensus_number_of_timeouts_as_leader metric tracks views where your node was the leader but failed to propose a block. Every jump in this counter means a missed proposal and warrants investigation.

Proposal Participation

Operators should also monitor their node's participation rate via the participation endpoints of another query node, for example the Espresso-hosted query service. These endpoints return per-epoch statistics:

curl https://query.main.net.espresso.network/v1/node/current-proposal-participation
curl https://query.main.net.espresso.network/v1/node/previous-proposal-participation

The response is a map of BLS public keys to participation scores. Look up your node's staking public key. A healthy node should have a value very close to 1.0. Values below 0.95 warrant investigation and reaching out to the Espresso team.

A temporary dip lasting up to one epoch is expected if a node was offline or recently restarted (~40,000 blocks / ~1 day on mainnet, ~3,000 blocks on decaf).

Endpoints

GET /status/block-height

The last known block height of the chain.

Returns integer

GET /status/success-rate

The fraction of views since genesis that resulted in a successful block. This equals the block height divided by the number of views completed.

Returns float

GET /status/time-since-last-decide

The elapsed time, in seconds, since consensus last decided on a block. Useful to alert when consensus is stalled or this node has been disconnected from consensus.

Returns integer

GET /status/metrics

Exposes all metrics recorded by consensus in Prometheus format.