.. _api: API (Restfull/JSON) documentation ================================= This documentation describes the Glances API version 4 (Restfull/JSON) interface. For Glances version 3, please have a look on: ``https://github.com/nicolargo/glances/blob/support/glancesv3/docs/api.rst`` Run the Glances API server -------------------------- The Glances Restfull/API server could be ran using the following command line: .. code-block:: bash # glances -w --disable-webui It is also ran automatically when Glances is started in Web server mode (-w). 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 URL --------------------- The API documentation is embeded in the server and 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 [{"avg": 73.31165502910655, "begin": 1710062583.0, "count": 1, "desc": "", "end": -1, "max": 73.31165502910655, "min": 73.31165502910655, "sort": "memory_percent", "state": "WARNING", "sum": 73.31165502910655, "top": [], "type": "MEM"}, {"avg": 88.6, "begin": 1710062583.0, "count": 1, "desc": "", "end": -1, "max": 88.6, "min": 88.6, "sort": "cpu_percent", "state": "CRITICAL", "sum": 88.6, "top": [], "type": "CPU_TOTAL"}] Fields descriptions: * **begin**: Begin timestamp of the event (unit is *timestamp*) * **end**: End timestamp of the event (or -1 if ongoing) (unit is *timestamp*) * **state**: State of the event (WARNING|CRITICAL) (unit is *string*) * **type**: Type of the event (CPU|LOAD|MEM) (unit is *string*) * **max**: Maximum value during the event period (unit is *float*) * **avg**: Average value during the event period (unit is *float*) * **min**: Minimum value during the event period (unit is *float*) * **sum**: Sum of the values during the event period (unit is *float*) * **count**: Number of values during the event period (unit is *int*) * **top**: Top 3 processes name during the event period (unit is *list*) * **desc**: Description of the event (unit is *string*) * **sort**: Sort key of the top processes (unit is *string*) Get a specific field:: # curl http://localhost:61208/api/4/alert/begin {"begin": [1710062583.0, 1710062583.0]} Get a specific item when field matches the given value:: # curl http://localhost:61208/api/4/alert/begin/1710062583.0 {"1710062583.0": [{"avg": 73.31165502910655, "begin": 1710062583.0, "count": 1, "desc": "", "end": -1, "max": 73.31165502910655, "min": 73.31165502910655, "sort": "memory_percent", "state": "WARNING", "sum": 73.31165502910655, "top": [], "type": "MEM"}, {"avg": 88.6, "begin": 1710062583.0, "count": 1, "desc": "", "end": -1, "max": 88.6, "min": 88.6, "sort": "cpu_percent", "state": "CRITICAL", "sum": 88.6, "top": [], "type": "CPU_TOTAL"}]} 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": 1.6637179851531982}, {"count": 0, "countmax": 20.0, "countmin": None, "key": "name", "name": "Python", "refresh": 3.0, "regex": True, "result": None, "timer": 1.6630256175994873}] Fields descriptions: * **name**: AMP name (unit is *None*) * **result**: AMP result (a string) (unit is *None*) * **refresh**: AMP refresh interval (unit is *second*) * **timer**: Time until next refresh (unit is *second*) * **count**: Number of matching processes (unit is *number*) * **countmin**: Minimum number of matching processes (unit is *number*) * **countmax**: Maximum number of matching processes (unit is *number*) 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": 1.6637179851531982}]} GET cloud --------- Get plugin stats:: # curl http://localhost:61208/api/4/cloud {} GET connections --------------- Get plugin stats:: # curl http://localhost:61208/api/4/connections {"net_connections_enabled": True, "nf_conntrack_enabled": True} Fields descriptions: * **LISTEN**: Number of TCP connections in LISTEN state (unit is *number*) * **ESTABLISHED**: Number of TCP connections in ESTABLISHED state (unit is *number*) * **SYN_SENT**: Number of TCP connections in SYN_SENT state (unit is *number*) * **SYN_RECV**: Number of TCP connections in SYN_RECV state (unit is *number*) * **initiated**: Number of TCP connections initiated (unit is *number*) * **terminated**: Number of TCP connections terminated (unit is *number*) * **nf_conntrack_count**: Number of tracked connections (unit is *number*) * **nf_conntrack_max**: Maximum number of tracked connections (unit is *number*) * **nf_conntrack_percent**: Percentage of tracked connections (unit is *percent*) 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 [{"command": "/portainer", "cpu": {"total": 0.0}, "cpu_percent": 0.0, "created": "2022-10-29T14:59:10.266701439Z", "engine": "docker", "id": "3abd51c615968482d9ccff5afc629f267f6dda113ed68b75b432615fae3b49fb", "image": ["portainer/portainer-ce:2.9.3"], "io": {"cumulative_ior": 180224, "cumulative_iow": 909312}, "key": "name", "memory": {"cache": None, "limit": 7823568896, "max_usage": None, "rss": None, "usage": 16605184}, "memory_usage": 16605184, "name": "portainer", "network": {"cumulative_rx": 2610910, "cumulative_tx": 0}, "status": "running", "uptime": "6 days"}] Fields descriptions: * **name**: Container name (unit is *None*) * **id**: Container ID (unit is *None*) * **image**: Container image (unit is *None*) * **status**: Container status (unit is *None*) * **created**: Container creation date (unit is *None*) * **command**: Container command (unit is *None*) * **cpu_percent**: Container CPU consumption (unit is *percent*) * **memory_usage**: Container memory usage (unit is *byte*) * **io_rx**: Container IO bytes read rate (unit is *bytepersecond*) * **io_wx**: Container IO bytes write rate (unit is *bytepersecond*) * **network_rx**: Container network RX bitrate (unit is *bitpersecond*) * **network_tx**: Container network TX bitrate (unit is *bitpersecond*) * **uptime**: Container uptime (unit is *None*) * **engine**: Container engine (Docker and Podman are currently supported) (unit is *None*) * **pod_name**: Pod name (only with Podman) (unit is *None*) * **pod_id**: Pod ID (only with Podman) (unit is *None*) Get a specific field:: # curl http://localhost:61208/api/4/containers/name {"name": ["portainer"]} Get a specific item when field matches the given value:: # curl http://localhost:61208/api/4/containers/name/portainer {"portainer": [{"command": "/portainer", "cpu": {"total": 0.0}, "cpu_percent": 0.0, "created": "2022-10-29T14:59:10.266701439Z", "engine": "docker", "id": "3abd51c615968482d9ccff5afc629f267f6dda113ed68b75b432615fae3b49fb", "image": ["portainer/portainer-ce:2.9.3"], "io": {"cumulative_ior": 180224, "cumulative_iow": 909312}, "key": "name", "memory": {"cache": None, "limit": 7823568896, "max_usage": None, "rss": None, "usage": 16605184}, "memory_usage": 16605184, "name": "portainer", "network": {"cumulative_rx": 2610910, "cumulative_tx": 0}, "status": "running", "uptime": "6 days"}]} GET core -------- Get plugin stats:: # curl http://localhost:61208/api/4/core {"log": 4, "phys": 2} Fields descriptions: * **phys**: Number of physical cores (hyper thread CPUs are excluded) (unit is *number*) * **log**: Number of logical CPUs. A logical CPU is the number of physical cores multiplied by the number of threads that can run on each core (unit is *number*) Get a specific field:: # curl http://localhost:61208/api/4/core/phys {"phys": 2} GET cpu ------- Get plugin stats:: # curl http://localhost:61208/api/4/cpu {"cpucore": 4, "ctx_switches": 165746774, "guest": 0.0, "idle": 11.3, "interrupts": 120848862, "iowait": 0.1, "irq": 0.0, "nice": 0.1, "soft_interrupts": 46867913, "steal": 0.0, "syscalls": 0, "system": 19.8, "total": 88.6, "user": 68.6} Fields descriptions: * **total**: Sum of all CPU percentages (except idle) (unit is *percent*) * **system**: Percent time spent in kernel space. System CPU time is the time spent running code in the Operating System kernel (unit is *percent*) * **user**: CPU percent time spent in user space. User CPU time is the time spent on the processor running your program's code (or code in libraries) (unit is *percent*) * **iowait**: *(Linux)*: percent time spent by the CPU waiting for I/O operations to complete (unit is *percent*) * **dpc**: *(Windows)*: time spent servicing deferred procedure calls (DPCs) (unit is *percent*) * **idle**: percent of CPU used by any program. Every program or task that runs on a computer system occupies a certain amount of processing time on the CPU. If the CPU has completed all tasks it is idle (unit is *percent*) * **irq**: *(Linux and BSD)*: percent time spent servicing/handling hardware/software interrupts. Time servicing interrupts (hardware + software) (unit is *percent*) * **nice**: *(Unix)*: percent time occupied by user level processes with a positive nice value. The time the CPU has spent running users' processes that have been *niced* (unit is *percent*) * **steal**: *(Linux)*: percentage of time a virtual CPU waits for a real CPU while the hypervisor is servicing another virtual processor (unit is *percent*) * **guest**: *(Linux)*: time spent running a virtual CPU for guest operating systems under the control of the Linux kernel (unit is *percent*) * **ctx_switches**: number of context switches (voluntary + involuntary) per second. A context switch is a procedure that a computer's CPU (central processing unit) follows to change from one task (or process) to another while ensuring that the tasks do not conflict (unit is *number*) * **ctx_switches_rate_per_sec**: number of context switches (voluntary + involuntary) per second. A context switch is a procedure that a computer's CPU (central processing unit) follows to change from one task (or process) to another while ensuring that the tasks do not conflict per second (unit is *number* per second) * **ctx_switches_gauge**: number of context switches (voluntary + involuntary) per second. A context switch is a procedure that a computer's CPU (central processing unit) follows to change from one task (or process) to another while ensuring that the tasks do not conflict (cumulative) (unit is *number*) * **interrupts**: number of interrupts per second (unit is *number*) * **interrupts_rate_per_sec**: number of interrupts per second per second (unit is *number* per second) * **interrupts_gauge**: number of interrupts per second (cumulative) (unit is *number*) * **soft_interrupts**: number of software interrupts per second. Always set to 0 on Windows and SunOS (unit is *number*) * **soft_interrupts_rate_per_sec**: number of software interrupts per second. Always set to 0 on Windows and SunOS per second (unit is *number* per second) * **soft_interrupts_gauge**: number of software interrupts per second. Always set to 0 on Windows and SunOS (cumulative) (unit is *number*) * **syscalls**: number of system calls per second. Always 0 on Linux OS (unit is *number*) * **syscalls_rate_per_sec**: number of system calls per second. Always 0 on Linux OS per second (unit is *number* per second) * **syscalls_gauge**: number of system calls per second. Always 0 on Linux OS (cumulative) (unit is *number*) * **cpucore**: Total number of CPU core (unit is *number*) * **time_since_update**: Number of seconds since last update (unit is *seconds*) * **time_since_update**: Number of seconds since last update (unit is *seconds*) Get a specific field:: # curl http://localhost:61208/api/4/cpu/total {"total": 88.6} GET diskio ---------- Get plugin stats:: # curl http://localhost:61208/api/4/diskio [{"disk_name": "sda", "key": "disk_name", "read_bytes": 40396791296, "read_count": 1064967, "write_bytes": 45440573440, "write_count": 637304}, {"disk_name": "sda1", "key": "disk_name", "read_bytes": 9610240, "read_count": 260, "write_bytes": 0, "write_count": 18}] Fields descriptions: * **disk_name**: Disk name (unit is *None*) * **read_count**: Number of reads (unit is *number*) * **read_count_rate_per_sec**: Number of reads per second (unit is *number* per second) * **read_count_gauge**: Number of reads (cumulative) (unit is *number*) * **write_count**: Number of writes (unit is *number*) * **write_count_rate_per_sec**: Number of writes per second (unit is *number* per second) * **write_count_gauge**: Number of writes (cumulative) (unit is *number*) * **read_bytes**: Number of bytes read (unit is *byte*) * **read_bytes_rate_per_sec**: Number of bytes read per second (unit is *byte* per second) * **read_bytes_gauge**: Number of bytes read (cumulative) (unit is *byte*) * **write_bytes**: Number of bytes written (unit is *byte*) * **write_bytes_rate_per_sec**: Number of bytes written per second (unit is *byte* per second) * **write_bytes_gauge**: Number of bytes written (cumulative) (unit is *byte*) * **time_since_update**: Number of seconds since last update (unit is *seconds*) Get a specific field:: # curl http://localhost:61208/api/4/diskio/disk_name {"disk_name": ["sda", "sda1", "sda2", "sda5", "dm-0", "dm-1"]} Get a specific item when field matches the given value:: # curl http://localhost:61208/api/4/diskio/disk_name/sda {"sda": [{"disk_name": "sda", "key": "disk_name", "read_bytes": 40396791296, "read_count": 1064967, "write_bytes": 45440573440, "write_count": 637304}]} GET folders ----------- Get plugin stats:: # curl http://localhost:61208/api/4/folders [] Fields descriptions: * **path**: Absolute path (unit is *None*) * **size**: Folder size in bytes (unit is *byte*) * **refresh**: Refresh interval in seconds (unit is *second*) * **errno**: Return code when retrieving folder size (0 is no error) (unit is *number*) * **careful**: Careful threshold in MB (unit is *megabyte*) * **warning**: Warning threshold in MB (unit is *megabyte*) * **critical**: Critical threshold in MB (unit is *megabyte*) GET fs ------ Get plugin stats:: # curl http://localhost:61208/api/4/fs [{"device_name": "/dev/mapper/ubuntu--gnome--vg-root", "free": 38577684480, "fs_type": "ext4", "key": "mnt_point", "mnt_point": "/", "percent": 83.3, "size": 243334156288, "used": 192369016832}, {"device_name": "zsfpool", "free": 31195136, "fs_type": "zfs", "key": "mnt_point", "mnt_point": "/zsfpool", "percent": 25.4, "size": 41811968, "used": 10616832}] Fields descriptions: * **device_name**: Device name (unit is *None*) * **fs_type**: File system type (unit is *None*) * **mnt_point**: Mount point (unit is *None*) * **size**: Total size (unit is *byte*) * **used**: Used size (unit is *byte*) * **free**: Free size (unit is *byte*) * **percent**: File system usage in percent (unit is *percent*) Get a specific field:: # curl http://localhost:61208/api/4/fs/mnt_point {"mnt_point": ["/", "/zsfpool", "/var/snap/firefox/common/host-hunspell"]} Get a specific item when field matches the given value:: # curl http://localhost:61208/api/4/fs/mnt_point// {"/": [{"device_name": "/dev/mapper/ubuntu--gnome--vg-root", "free": 38577684480, "fs_type": "ext4", "key": "mnt_point", "mnt_point": "/", "percent": 83.3, "size": 243334156288, "used": 192369016832}]} GET gpu ------- Get plugin stats:: # curl http://localhost:61208/api/4/gpu [] Fields descriptions: * **gpu_id**: GPU identification (unit is *None*) * **name**: GPU name (unit is *None*) * **mem**: Memory consumption (unit is *percent*) * **proc**: GPU processor consumption (unit is *percent*) * **temperature**: GPU temperature (unit is *celsius*) * **fan_speed**: GPU fan speed (unit is *roundperminute*) GET help -------- Get plugin stats:: # curl http://localhost:61208/api/4/help None GET ip ------ Get plugin stats:: # curl http://localhost:61208/api/4/ip {"address": "192.168.1.14", "gateway": "192.168.1.1", "mask": "255.255.255.0", "mask_cidr": 24, "public_address": "92.151.148.66", "public_info_human": ""} Fields descriptions: * **address**: Private IP address (unit is *None*) * **mask**: Private IP mask (unit is *None*) * **mask_cidr**: Private IP mask in CIDR format (unit is *number*) * **gateway**: Private IP gateway (unit is *None*) * **public_address**: Public IP address (unit is *None*) * **public_info_human**: Public IP information (unit is *None*) Get a specific field:: # curl http://localhost:61208/api/4/ip/gateway {"gateway": "192.168.1.1"} GET irq ------- Get plugin stats:: # curl http://localhost:61208/api/4/irq [] Fields descriptions: * **irq_line**: IRQ line name (unit is *None*) * **irq_rate**: IRQ rate per second (unit is *numberpersecond*) GET load -------- Get plugin stats:: # curl http://localhost:61208/api/4/load {"cpucore": 4, "min1": 2.56787109375, "min15": 2.36572265625, "min5": 3.12109375} Fields descriptions: * **min1**: Average sum of the number of processes waiting in the run-queue plus the number currently executing over 1 minute (unit is *float*) * **min5**: Average sum of the number of processes waiting in the run-queue plus the number currently executing over 5 minutes (unit is *float*) * **min15**: Average sum of the number of processes waiting in the run-queue plus the number currently executing over 15 minutes (unit is *float*) * **cpucore**: Total number of CPU core (unit is *number*) Get a specific field:: # curl http://localhost:61208/api/4/load/min1 {"min1": 2.56787109375} GET mem ------- Get plugin stats:: # curl http://localhost:61208/api/4/mem {"active": 2670919680, "available": 2087981056, "buffers": 198955008, "cached": 2738225152, "free": 2087981056, "inactive": 3538657280, "percent": 73.3, "shared": 808251392, "total": 7823568896, "used": 5735587840} Fields descriptions: * **total**: Total physical memory available (unit is *bytes*) * **available**: The actual amount of available memory that can be given instantly to processes that request more memory in bytes; this is calculated by summing different memory values depending on the platform (e.g. free + buffers + cached on Linux) and it is supposed to be used to monitor actual memory usage in a cross platform fashion (unit is *bytes*) * **percent**: The percentage usage calculated as (total - available) / total * 100 (unit is *percent*) * **used**: Memory used, calculated differently depending on the platform and designed for informational purposes only (unit is *bytes*) * **free**: Memory not being used at all (zeroed) that is readily available; note that this doesn't reflect the actual memory available (use 'available' instead) (unit is *bytes*) * **active**: *(UNIX)*: memory currently in use or very recently used, and so it is in RAM (unit is *bytes*) * **inactive**: *(UNIX)*: memory that is marked as not used (unit is *bytes*) * **buffers**: *(Linux, BSD)*: cache for things like file system metadata (unit is *bytes*) * **cached**: *(Linux, BSD)*: cache for various things (unit is *bytes*) * **wired**: *(BSD, macOS)*: memory that is marked to always stay in RAM. It is never moved to disk (unit is *bytes*) * **shared**: *(BSD)*: memory that may be simultaneously accessed by multiple processes (unit is *bytes*) Get a specific field:: # curl http://localhost:61208/api/4/mem/total {"total": 7823568896} GET memswap ----------- Get plugin stats:: # curl http://localhost:61208/api/4/memswap {"free": 6323769344, "percent": 21.8, "sin": 1142206464, "sout": 2868031488, "time_since_update": 1, "total": 8082419712, "used": 1758650368} Fields descriptions: * **total**: Total swap memory (unit is *bytes*) * **used**: Used swap memory (unit is *bytes*) * **free**: Free swap memory (unit is *bytes*) * **percent**: Used swap memory in percentage (unit is *percent*) * **sin**: The number of bytes the system has swapped in from disk (cumulative) (unit is *bytes*) * **sout**: The number of bytes the system has swapped out from disk (cumulative) (unit is *bytes*) * **time_since_update**: Number of seconds since last update (unit is *seconds*) Get a specific field:: # curl http://localhost:61208/api/4/memswap/total {"total": 8082419712} GET network ----------- Get plugin stats:: # curl http://localhost:61208/api/4/network [{"alias": None, "bytes_all": 0, "bytes_all_gauge": 3042797866, "bytes_recv": 0, "bytes_recv_gauge": 2894285066, "bytes_sent": 0, "bytes_sent_gauge": 148512800, "interface_name": "wlp2s0", "key": "interface_name", "speed": 0, "time_since_update": 1.1531965732574463}, {"alias": None, "bytes_all": 0, "bytes_all_gauge": 0, "bytes_recv": 0, "bytes_recv_gauge": 0, "bytes_sent": 0, "bytes_sent_gauge": 0, "interface_name": "br-40875d2e2716", "key": "interface_name", "speed": 0, "time_since_update": 1.1531965732574463}] Fields descriptions: * **interface_name**: Interface name (unit is *None*) * **alias**: Interface alias name (optional) (unit is *None*) * **bytes_recv**: Number of bytes received (unit is *byte*) * **bytes_recv_rate_per_sec**: Number of bytes received per second (unit is *byte* per second) * **bytes_recv_gauge**: Number of bytes received (cumulative) (unit is *byte*) * **bytes_sent**: Number of bytes sent (unit is *byte*) * **bytes_sent_rate_per_sec**: Number of bytes sent per second (unit is *byte* per second) * **bytes_sent_gauge**: Number of bytes sent (cumulative) (unit is *byte*) * **bytes_all**: Number of bytes received and sent (unit is *byte*) * **bytes_all_rate_per_sec**: Number of bytes received and sent per second (unit is *byte* per second) * **bytes_all_gauge**: Number of bytes received and sent (cumulative) (unit is *byte*) * **speed**: Maximum interface speed (in bit per second). Can return 0 on some operating-system (unit is *bitpersecond*) * **is_up**: Is the interface up ? (unit is *bool*) * **time_since_update**: Number of seconds since last update (unit is *seconds*) Get a specific field:: # curl http://localhost:61208/api/4/network/interface_name {"interface_name": ["wlp2s0", "br-40875d2e2716", "br_grafana", "vethe9e9c35", "lxdbr0", "veth05608da0", "mpqemubr0"]} Get a specific item when field matches the given value:: # curl http://localhost:61208/api/4/network/interface_name/wlp2s0 {"wlp2s0": [{"alias": None, "bytes_all": 0, "bytes_all_gauge": 3042797866, "bytes_recv": 0, "bytes_recv_gauge": 2894285066, "bytes_sent": 0, "bytes_sent_gauge": 148512800, "interface_name": "wlp2s0", "key": "interface_name", "speed": 0, "time_since_update": 1.1531965732574463}]} GET now ------- Get plugin stats:: # curl http://localhost:61208/api/4/now "2024-03-10 10:23:03 CET" GET percpu ---------- Get plugin stats:: # curl http://localhost:61208/api/4/percpu [{"cpu_number": 0, "guest": 0.0, "guest_nice": 0.0, "idle": 12.2, "iowait": 0.0, "irq": 0.0, "key": "cpu_number", "nice": 0.5, "softirq": 0.0, "steal": 0.0, "system": 24.3, "total": 87.8, "user": 63.1}, {"cpu_number": 1, "guest": 0.0, "guest_nice": 0.0, "idle": 15.6, "iowait": 0.0, "irq": 0.0, "key": "cpu_number", "nice": 0.0, "softirq": 0.0, "steal": 0.0, "system": 13.3, "total": 84.4, "user": 71.1}] Fields descriptions: * **cpu_number**: CPU number (unit is *None*) * **total**: Sum of CPU percentages (except idle) for current CPU number (unit is *percent*) * **system**: Percent time spent in kernel space. System CPU time is the time spent running code in the Operating System kernel (unit is *percent*) * **user**: CPU percent time spent in user space. User CPU time is the time spent on the processor running your program's code (or code in libraries) (unit is *percent*) * **iowait**: *(Linux)*: percent time spent by the CPU waiting for I/O operations to complete (unit is *percent*) * **idle**: percent of CPU used by any program. Every program or task that runs on a computer system occupies a certain amount of processing time on the CPU. If the CPU has completed all tasks it is idle (unit is *percent*) * **irq**: *(Linux and BSD)*: percent time spent servicing/handling hardware/software interrupts. Time servicing interrupts (hardware + software) (unit is *percent*) * **nice**: *(Unix)*: percent time occupied by user level processes with a positive nice value. The time the CPU has spent running users' processes that have been *niced* (unit is *percent*) * **steal**: *(Linux)*: percentage of time a virtual CPU waits for a real CPU while the hypervisor is servicing another virtual processor (unit is *percent*) * **guest**: *(Linux)*: percent of time spent running a virtual CPU for guest operating systems under the control of the Linux kernel (unit is *percent*) * **guest_nice**: *(Linux)*: percent of time spent running a niced guest (virtual CPU) (unit is *percent*) * **softirq**: *(Linux)*: percent of time spent handling software interrupts (unit is *percent*) Get a specific field:: # curl http://localhost:61208/api/4/percpu/cpu_number {"cpu_number": [0, 1, 2, 3]} GET ports --------- Get plugin stats:: # curl http://localhost:61208/api/4/ports [{"description": "DefaultGateway", "host": "192.168.1.1", "indice": "port_0", "port": 0, "refresh": 30, "rtt_warning": None, "status": 0.012084, "timeout": 3}] Fields descriptions: * **host**: Measurement is be done on this host (or IP address) (unit is *None*) * **port**: Measurement is be done on this port (0 for ICMP) (unit is *None*) * **description**: Human readable description for the host/port (unit is *None*) * **refresh**: Refresh time (in seconds) for this host/port (unit is *None*) * **timeout**: Timeout (in seconds) for the measurement (unit is *None*) * **status**: Measurement result (in seconds) (unit is *second*) * **rtt_warning**: Warning threshold (in seconds) for the measurement (unit is *second*) * **indice**: Unique indice for the host/port (unit is *None*) Get a specific field:: # curl http://localhost:61208/api/4/ports/host {"host": ["192.168.1.1"]} Get a specific item when field matches the given value:: # curl http://localhost:61208/api/4/ports/host/192.168.1.1 {"192.168.1.1": [{"description": "DefaultGateway", "host": "192.168.1.1", "indice": "port_0", "port": 0, "refresh": 30, "rtt_warning": None, "status": 0.012084, "timeout": 3}]} GET processcount ---------------- Get plugin stats:: # curl http://localhost:61208/api/4/processcount {"pid_max": 0, "running": 3, "sleeping": 328, "thread": 1568, "total": 397} Fields descriptions: * **total**: Total number of processes (unit is *number*) * **running**: Total number of running processes (unit is *number*) * **sleeping**: Total number of sleeping processes (unit is *number*) * **thread**: Total number of threads (unit is *number*) * **pid_max**: Maximum number of processes (unit is *number*) Get a specific field:: # curl http://localhost:61208/api/4/processcount/total {"total": 397} GET processlist --------------- Get plugin stats:: # curl http://localhost:61208/api/4/processlist [] Fields descriptions: * **pid**: Process identifier (ID) (unit is *number*) * **name**: Process name (unit is *string*) * **cmdline**: Command line with arguments (unit is *list*) * **username**: Process owner (unit is *string*) * **num_threads**: Number of threads (unit is *number*) * **cpu_percent**: Process CPU consumption (unit is *percent*) * **memory_percent**: Process memory consumption (unit is *percent*) * **memory_info**: Process memory information (dict with rss, vms, shared, text, lib, data, dirty keys) (unit is *byte*) * **status**: Process status (unit is *string*) * **nice**: Process nice value (unit is *number*) * **cpu_times**: Process CPU times (dict with user, system, iowait keys) (unit is *second*) * **gids**: Process group IDs (dict with real, effective, saved keys) (unit is *number*) * **io_counters**: Process IO counters (list with read_count, write_count, read_bytes, write_bytes, io_tag keys) (unit is *byte*) GET psutilversion ----------------- Get plugin stats:: # curl http://localhost:61208/api/4/psutilversion "5.9.8" GET quicklook ------------- Get plugin stats:: # curl http://localhost:61208/api/4/quicklook {"cpu": 88.6, "cpu_hz": 2025000000.0, "cpu_hz_current": 1348598250.0, "cpu_name": "Intel(R) Core(TM) i7-4500U CPU @ 1.80GHz", "cpucore": 4, "load": 59.1, "mem": 73.3, "percpu": [{"cpu_number": 0, "guest": 0.0, "guest_nice": 0.0, "idle": 12.2, "iowait": 0.0, "irq": 0.0, "key": "cpu_number", "nice": 0.5, "softirq": 0.0, "steal": 0.0, "system": 24.3, "total": 87.8, "user": 63.1}, {"cpu_number": 1, "guest": 0.0, "guest_nice": 0.0, "idle": 15.6, "iowait": 0.0, "irq": 0.0, "key": "cpu_number", "nice": 0.0, "softirq": 0.0, "steal": 0.0, "system": 13.3, "total": 84.4, "user": 71.1}, {"cpu_number": 2, "guest": 0.0, "guest_nice": 0.0, "idle": 7.2, "iowait": 0.0, "irq": 0.0, "key": "cpu_number", "nice": 0.0, "softirq": 0.0, "steal": 0.0, "system": 24.4, "total": 92.8, "user": 68.3}, {"cpu_number": 3, "guest": 0.0, "guest_nice": 0.0, "idle": 12.5, "iowait": 0.0, "irq": 0.0, "key": "cpu_number", "nice": 0.0, "softirq": 0.0, "steal": 0.0, "system": 17.0, "total": 87.5, "user": 70.5}], "swap": 21.8} Fields descriptions: * **cpu**: CPU percent usage (unit is *percent*) * **mem**: MEM percent usage (unit is *percent*) * **swap**: SWAP percent usage (unit is *percent*) * **load**: LOAD percent usage (unit is *percent*) * **cpu_name**: CPU name (unit is *None*) * **cpu_hz_current**: CPU current frequency (unit is *hertz*) * **cpu_hz**: CPU max frequency (unit is *hertz*) Get a specific field:: # curl http://localhost:61208/api/4/quicklook/cpu_name {"cpu_name": "Intel(R) Core(TM) i7-4500U CPU @ 1.80GHz"} GET raid -------- Get plugin stats:: # curl http://localhost:61208/api/4/raid {} GET sensors ----------- Get plugin stats:: # curl http://localhost:61208/api/4/sensors [{"critical": 105, "key": "label", "label": "acpitz 0", "type": "temperature_core", "unit": "C", "value": 27, "warning": 105}, {"critical": 105, "key": "label", "label": "acpitz 1", "type": "temperature_core", "unit": "C", "value": 29, "warning": 105}] Fields descriptions: * **label**: Sensor label (unit is *None*) * **unit**: Sensor unit (unit is *None*) * **value**: Sensor value (unit is *number*) * **warning**: Warning threshold (unit is *number*) * **critical**: Critical threshold (unit is *number*) * **type**: Sensor type (one of battery, temperature_core, fan_speed) (unit is *None*) Get a specific field:: # curl http://localhost:61208/api/4/sensors/label {"label": ["acpitz 0", "acpitz 1", "Package id 0", "Core 0", "Core 1", "CPU", "Ambient", "SODIMM", "BAT BAT0"]} Get a specific item when field matches the given value:: # curl http://localhost:61208/api/4/sensors/label/acpitz 0 {"acpitz 0": [{"critical": 105, "key": "label", "label": "acpitz 0", "type": "temperature_core", "unit": "C", "value": 27, "warning": 105}]} GET smart --------- Get plugin stats:: # curl http://localhost:61208/api/4/smart {} GET system ---------- Get plugin stats:: # curl http://localhost:61208/api/4/system {"hostname": "XPS13-9333", "hr_name": "Ubuntu 22.04 64bit / Linux 5.15.0-94-generic", "linux_distro": "Ubuntu 22.04", "os_name": "Linux", "os_version": "5.15.0-94-generic", "platform": "64bit"} Fields descriptions: * **os_name**: Operating system name (unit is *None*) * **hostname**: Hostname (unit is *None*) * **platform**: Platform (32 or 64 bits) (unit is *None*) * **linux_distro**: Linux distribution (unit is *None*) * **os_version**: Operating system version (unit is *None*) * **hr_name**: Human readable operating sytem name (unit is *None*) Get a specific field:: # curl http://localhost:61208/api/4/system/os_name {"os_name": "Linux"} GET uptime ---------- Get plugin stats:: # curl http://localhost:61208/api/4/uptime "6 days, 1:22:24" GET version ----------- Get plugin stats:: # curl http://localhost:61208/api/4/version "4.0.0_beta01" GET wifi -------- Get plugin stats:: # curl http://localhost:61208/api/4/wifi [] GET all stats ------------- Get all Glances stats:: # curl http://localhost:61208/api/4/all Return a very big dictionary (avoid using this request, performances will be poor)... GET top n items of a specific plugin ------------------------------------ Get top 2 processes of the processlist plugin:: # curl http://localhost:61208/api/4/processlist/top/2 [{"cmdline": ["/usr/share/code/code", "--type=renderer", "--crashpad-handler-pid=35523", "--enable-crash-reporter=721e05a9-6035-4dcb-bd58-68097aa48dd0,no_channel", "--user-data-dir=/home/nicolargo/.config/Code", "--standard-schemes=vscode-webview,vscode-file", "--enable-sandbox", "--secure-schemes=vscode-webview,vscode-file", "--cors-schemes=vscode-webview,vscode-file", "--fetch-schemes=vscode-webview,vscode-file", "--service-worker-schemes=vscode-webview", "--code-cache-schemes=vscode-webview,vscode-file", "--app-path=/usr/share/code/resources/app", "--enable-sandbox", "--enable-blink-features=HighlightAPI", "--first-renderer-process", "--lang=en-US", "--num-raster-threads=2", "--enable-main-frame-before-activation", "--renderer-client-id=4", "--time-ticks-at-unix-epoch=-1709539275787032", "--launch-time-ticks=3773104105", "--shared-files=v8_context_snapshot_data:100", "--field-trial-handle=0,i,2992833077465328896,17440056338018087593,262144", "--disable-features=CalculateNativeWinOcclusion,SpareRendererForSitePerProcess", "--vscode-window-config=vscode:0a3f42ef-a12c-453d-8061-6c7b57ac6b4f"], "cpu_percent": 0.0, "cpu_times": {"children_system": 0.0, "children_user": 0.0, "iowait": 0.0, "system": 172.62, "user": 1890.5}, "gids": {"effective": 1000, "real": 1000, "saved": 1000}, "io_counters": [171679744, 3170304, 0, 0, 0], "key": "pid", "memory_info": {"data": 854614016, "dirty": 0, "lib": 0, "rss": 422739968, "shared": 58146816, "text": 126423040, "vms": 1221788676096}, "memory_percent": 5.403415929731719, "name": "code", "nice": 0, "num_threads": 15, "pid": 35570, "status": "R", "time_since_update": 1, "username": "nicolargo"}, {"cmdline": ["/snap/firefox/3728/usr/lib/firefox/firefox"], "cpu_percent": 0.0, "cpu_times": {"children_system": 426.4, "children_user": 3014.69, "iowait": 0.0, "system": 985.57, "user": 3348.95}, "gids": {"effective": 1000, "real": 1000, "saved": 1000}, "io_counters": [2248550400, 3508150272, 0, 0, 0], "key": "pid", "memory_info": {"data": 1414733824, "dirty": 0, "lib": 0, "rss": 397053952, "shared": 119676928, "text": 839680, "vms": 13362327552}, "memory_percent": 5.075100088950505, "name": "firefox", "nice": 0, "num_threads": 151, "pid": 7992, "status": "S", "time_since_update": 1, "username": "nicolargo"}] Note: Only work for plugin with a list of items GET item description -------------------- Get item description (human readable) for a specific plugin/item:: # curl http://localhost:61208/api/4/diskio/read_bytes/description "Number of bytes read." Note: the description is defined in the fields_description variable of the plugin. GET item unit ------------- Get item unit for a specific plugin/item:: # curl http://localhost:61208/api/4/diskio/read_bytes/unit "byte" Note: the description is defined in the fields_description variable of the plugin. GET stats history ----------------- History of a plugin:: # curl http://localhost:61208/api/4/cpu/history {"system": [["2024-03-10T10:23:06.365225", 13.3], ["2024-03-10T10:23:07.430118", 13.3], ["2024-03-10T10:23:08.929720", 11.4]], "user": [["2024-03-10T10:23:06.365190", 69.0], ["2024-03-10T10:23:07.430085", 69.0], ["2024-03-10T10:23:08.929700", 23.1]]} Limit history to last 2 values:: # curl http://localhost:61208/api/4/cpu/history/2 {"system": [["2024-03-10T10:23:07.430118", 13.3], ["2024-03-10T10:23:08.929720", 11.4]], "user": [["2024-03-10T10:23:07.430085", 69.0], ["2024-03-10T10:23:08.929700", 23.1]]} History for a specific field:: # curl http://localhost:61208/api/4/cpu/system/history {"system": [["2024-03-10T10:23:03.872029", 19.8], ["2024-03-10T10:23:06.365225", 13.3], ["2024-03-10T10:23:07.430118", 13.3], ["2024-03-10T10:23:08.929720", 11.4]]} Limit history for a specific field to last 2 values:: # curl http://localhost:61208/api/4/cpu/system/history {"system": [["2024-03-10T10:23:07.430118", 13.3], ["2024-03-10T10:23:08.929720", 11.4]]} GET limits (used for thresholds) -------------------------------- All limits/thresholds:: # curl http://localhost:61208/api/4/all/limits {"alert": {"alert_disable": ["False"], "history_size": 1200.0}, "amps": {"amps_disable": ["False"], "history_size": 1200.0}, "containers": {"containers_all": ["False"], "containers_disable": ["False"], "containers_max_name_size": 20.0, "history_size": 1200.0}, "core": {"history_size": 1200.0}, "cpu": {"cpu_ctx_switches_careful": 160000.0, "cpu_ctx_switches_critical": 200000.0, "cpu_ctx_switches_warning": 180000.0, "cpu_disable": ["False"], "cpu_iowait_careful": 20.0, "cpu_iowait_critical": 25.0, "cpu_iowait_warning": 22.5, "cpu_steal_careful": 50.0, "cpu_steal_critical": 90.0, "cpu_steal_warning": 70.0, "cpu_system_careful": 50.0, "cpu_system_critical": 90.0, "cpu_system_log": ["False"], "cpu_system_warning": 70.0, "cpu_total_careful": 65.0, "cpu_total_critical": 85.0, "cpu_total_log": ["True"], "cpu_total_warning": 75.0, "cpu_user_careful": 50.0, "cpu_user_critical": 90.0, "cpu_user_log": ["False"], "cpu_user_warning": 70.0, "history_size": 1200.0}, "diskio": {"diskio_disable": ["False"], "diskio_hide": ["loop.*", "/dev/loop.*"], "history_size": 1200.0}, "folders": {"folders_disable": ["False"], "history_size": 1200.0}, "fs": {"fs_careful": 50.0, "fs_critical": 90.0, "fs_disable": ["False"], "fs_hide": ["/boot.*", "/snap.*"], "fs_warning": 70.0, "history_size": 1200.0}, "gpu": {"gpu_disable": ["False"], "gpu_mem_careful": 50.0, "gpu_mem_critical": 90.0, "gpu_mem_warning": 70.0, "gpu_proc_careful": 50.0, "gpu_proc_critical": 90.0, "gpu_proc_warning": 70.0, "history_size": 1200.0}, "help": {"history_size": 1200.0}, "ip": {"history_size": 1200.0, "ip_censys_fields": ["location:continent", "location:country", "autonomous_system:name"], "ip_censys_url": ["https://search.censys.io/api"], "ip_disable": ["False"], "ip_public_ip_disabled": ["False"], "ip_public_refresh_interval": 300.0}, "load": {"history_size": 1200.0, "load_careful": 0.7, "load_critical": 5.0, "load_disable": ["False"], "load_warning": 1.0}, "mem": {"history_size": 1200.0, "mem_careful": 50.0, "mem_critical": 90.0, "mem_disable": ["False"], "mem_warning": 70.0}, "memswap": {"history_size": 1200.0, "memswap_careful": 50.0, "memswap_critical": 90.0, "memswap_disable": ["False"], "memswap_warning": 70.0}, "network": {"history_size": 1200.0, "network_disable": ["False"], "network_hide": ["docker.*", "lo"], "network_rx_careful": 70.0, "network_rx_critical": 90.0, "network_rx_warning": 80.0, "network_tx_careful": 70.0, "network_tx_critical": 90.0, "network_tx_warning": 80.0}, "now": {"history_size": 1200.0}, "percpu": {"history_size": 1200.0, "percpu_disable": ["False"], "percpu_iowait_careful": 50.0, "percpu_iowait_critical": 90.0, "percpu_iowait_warning": 70.0, "percpu_system_careful": 50.0, "percpu_system_critical": 90.0, "percpu_system_warning": 70.0, "percpu_user_careful": 50.0, "percpu_user_critical": 90.0, "percpu_user_warning": 70.0}, "ports": {"history_size": 1200.0, "ports_disable": ["False"], "ports_port_default_gateway": ["True"], "ports_refresh": 30.0, "ports_timeout": 3.0}, "processcount": {"history_size": 1200.0, "processcount_disable": ["False"]}, "processlist": {"history_size": 1200.0, "processlist_cpu_careful": 50.0, "processlist_cpu_critical": 90.0, "processlist_cpu_warning": 70.0, "processlist_disable": ["False"], "processlist_mem_careful": 50.0, "processlist_mem_critical": 90.0, "processlist_mem_warning": 70.0, "processlist_nice_warning": ["-20", "-19", "-18", "-17", "-16", "-15", "-14", "-13", "-12", "-11", "-10", "-9", "-8", "-7", "-6", "-5", "-4", "-3", "-2", "-1", "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15", "16", "17", "18", "19"]}, "psutilversion": {"history_size": 1200.0}, "quicklook": {"history_size": 1200.0, "quicklook_bar_char": ["|"], "quicklook_cpu_careful": 50.0, "quicklook_cpu_critical": 90.0, "quicklook_cpu_warning": 70.0, "quicklook_disable": ["False"], "quicklook_list": ["cpu", "mem", "load"], "quicklook_load_careful": 70.0, "quicklook_load_critical": 500.0, "quicklook_load_warning": 100.0, "quicklook_mem_careful": 50.0, "quicklook_mem_critical": 90.0, "quicklook_mem_warning": 70.0, "quicklook_swap_careful": 50.0, "quicklook_swap_critical": 90.0, "quicklook_swap_warning": 70.0}, "sensors": {"history_size": 1200.0, "sensors_battery_careful": 80.0, "sensors_battery_critical": 95.0, "sensors_battery_warning": 90.0, "sensors_disable": ["False"], "sensors_refresh": 4.0, "sensors_temperature_core_careful": 60.0, "sensors_temperature_core_critical": 80.0, "sensors_temperature_core_warning": 70.0, "sensors_temperature_hdd_careful": 45.0, "sensors_temperature_hdd_critical": 60.0, "sensors_temperature_hdd_warning": 52.0}, "system": {"history_size": 1200.0, "system_disable": ["False"], "system_refresh": 60}, "uptime": {"history_size": 1200.0}, "version": {"history_size": 1200.0}, "wifi": {"history_size": 1200.0, "wifi_careful": -65.0, "wifi_critical": -85.0, "wifi_disable": ["False"], "wifi_warning": -75.0}} Limits/thresholds for the cpu plugin:: # curl http://localhost:61208/api/4/cpu/limits {"cpu_ctx_switches_careful": 160000.0, "cpu_ctx_switches_critical": 200000.0, "cpu_ctx_switches_warning": 180000.0, "cpu_disable": ["False"], "cpu_iowait_careful": 20.0, "cpu_iowait_critical": 25.0, "cpu_iowait_warning": 22.5, "cpu_steal_careful": 50.0, "cpu_steal_critical": 90.0, "cpu_steal_warning": 70.0, "cpu_system_careful": 50.0, "cpu_system_critical": 90.0, "cpu_system_log": ["False"], "cpu_system_warning": 70.0, "cpu_total_careful": 65.0, "cpu_total_critical": 85.0, "cpu_total_log": ["True"], "cpu_total_warning": 75.0, "cpu_user_careful": 50.0, "cpu_user_critical": 90.0, "cpu_user_log": ["False"], "cpu_user_warning": 70.0, "history_size": 1200.0}