.. _api:
API (Restfull/JSON) documentation
=================================
The Glances Restfull/API server could be ran using the following command line:
.. code-block:: bash
# glances -w --disable-webui
API URL
-------
The default root API URL is ``http://localhost:61208/api/4``.
The bind address and port could be changed using the ``--bind`` and ``--port`` command line options.
It is also possible to define an URL prefix using the ``url_prefix`` option from the [outputs] section
of the Glances configuration file.
Note: The url_prefix should always end with a slash (``/``).
For example:
.. code-block:: ini
[outputs]
url_prefix = /glances/
will change the root API URL to ``http://localhost:61208/glances/api/4`` and the Web UI URL to
``http://localhost:61208/glances/``
API documentation
-----------------
The API documentation is available at the following URL: ``http://localhost:61208/docs#/``.
WebUI refresh
-------------
It is possible to change the Web UI refresh rate (default is 2 seconds) using the following option in the URL:
``http://localhost:61208/glances/?refresh=5``
GET API status
--------------
This entry point should be used to check the API status.
It will the Glances version and a 200 return code if everything is OK.
Get the Rest API status::
# curl -I http://localhost:61208/api/4/status
"HTTP/1.0 200 OK"
GET plugins list
----------------
Get the plugins list::
# curl http://localhost:61208/api/4/pluginslist
["alert",
"amps",
"cloud",
"connections",
"containers",
"core",
"cpu",
"diskio",
"folders",
"fs",
"gpu",
"help",
"ip",
"irq",
"load",
"mem",
"memswap",
"network",
"now",
"percpu",
"ports",
"processcount",
"processlist",
"psutilversion",
"quicklook",
"raid",
"sensors",
"smart",
"system",
"uptime",
"version",
"wifi"]
GET alert
---------
Get plugin stats::
# curl http://localhost:61208/api/4/alert
[[1702733581.0,
-1,
"WARNING",
"MEM",
80.72395821062744,
80.72395821062744,
80.72395821062744,
80.72395821062744,
1,
[],
"",
"memory_percent"]]
GET amps
--------
Get plugin stats::
# curl http://localhost:61208/api/4/amps
[{"count": 0,
"countmax": None,
"countmin": 1.0,
"key": "name",
"name": "Dropbox",
"refresh": 3.0,
"regex": True,
"result": None,
"timer": 0.30402588844299316},
{"count": 0,
"countmax": 20.0,
"countmin": None,
"key": "name",
"name": "Python",
"refresh": 3.0,
"regex": True,
"result": None,
"timer": 0.3038666248321533}]
Get a specific field::
# curl http://localhost:61208/api/4/amps/name
{"name": ["Dropbox", "Python", "Conntrack", "Nginx", "Systemd", "SystemV"]}
Get a specific item when field matches the given value::
# curl http://localhost:61208/api/4/amps/name/Dropbox
{"Dropbox": [{"count": 0,
"countmax": None,
"countmin": 1.0,
"key": "name",
"name": "Dropbox",
"refresh": 3.0,
"regex": True,
"result": None,
"timer": 0.30402588844299316}]}
GET connections
---------------
Get plugin stats::
# curl http://localhost:61208/api/4/connections
{"net_connections_enabled": True, "nf_conntrack_enabled": True}
Get a specific field::
# curl http://localhost:61208/api/4/connections/net_connections_enabled
{"net_connections_enabled": True}
GET containers
--------------
Get plugin stats::
# curl http://localhost:61208/api/4/containers
{"containers": [{"Command": ["/portainer"],
"Created": "2022-10-29T14:59:10.266701439Z",
"Id": "3abd51c615968482d9ccff5afc629f267f6dda113ed68b75b432615fae3b49fb",
"Image": ["portainer/portainer-ce:2.9.3"],
"Status": "running",
"Uptime": "3 weeks",
"cpu": {"total": 0.0},
"cpu_percent": 0.0,
"engine": "docker",
"io": {"cumulative_ior": 1904640, "cumulative_iow": 2256896},
"io_r": None,
"io_w": None,
"key": "name",
"memory": {"cache": None,
"limit": 7823585280,
"max_usage": None,
"rss": None,
"usage": 13836288},
"memory_usage": 13836288,
"name": "portainer",
"network": {"cumulative_rx": 7106388, "cumulative_tx": 0},
"network_rx": None,
"network_tx": None},
{"Command": ["top"],
"Created": "2023-12-09T10:45:34.339489876+01:00",
"Id": "481d6ffb7eef284d062628cf350bdd9ce0a803db8a2a505d75565ed24322b714",
"Image": "["docker.io/library/ubuntu:latest"]",
"Status": "running",
"Uptime": "1 weeks",
"cpu": {"total": 6.604897042562196e-07},
"cpu_percent": 6.604897042562196e-07,
"engine": "podman",
"io": {"ior": 0.0, "iow": 0.0, "time_since_update": 1},
"io_r": 0.0,
"io_w": 0.0,
"key": "name",