List active agents

GET 
/api/agent

Discover all active agents in the fleet.

Responses

200

List of active agents.

application/json

Schema

Schema

agents

object[]

required

Array [

machine_id string

The permanent machine identifier.

fingerprint string

The SHA256 fingerprint of the agent's PKI public key. Empty when PKI is disabled.

hostname stringrequired

The hostname of the agent.

status stringrequired

Possible values: [Ready, NotReady]

The current status of the agent.

labels

object

Key-value labels configured on the agent.

property name* string

registered_at date-time

When the agent last refreshed its heartbeat.

started_at date-time

When the agent process started.

os_info

object

Operating system information.

distribution stringrequired

The name of the Linux distribution.

version stringrequired

The version of the Linux distribution.

uptime string

The system uptime.

load_average

object

The system load averages for 1, 5, and 15 minutes.

1min numberrequired

Load average for the last 1 minute.

5min numberrequired

Load average for the last 5 minutes.

15min numberrequired

Load average for the last 15 minutes.

memory

object

Memory usage information.

total integerrequired

Total memory in bytes.

free integerrequired

Free memory in bytes.

used integerrequired

Used memory in bytes.

architecture string

CPU architecture.

kernel_version string

OS kernel version.

cpu_count integer

Number of logical CPUs.

fqdn string

Fully qualified domain name.

service_mgr string

Init system.

package_mgr string

Package manager.

interfaces

object[]

Array [

name stringrequired

ipv4 string

ipv6 string

mac string

family string

Possible values: [inet, inet6, dual]

IP address family.

]

primary_interface string

Name of the interface used for the default route.

routes

object[]

Network routing table entries.

Array [

destination stringrequired

Destination network address.

gateway stringrequired

Gateway address.

interface stringrequired

Network interface name.

mask string

Network mask in CIDR notation.

metric integer

Route metric.

flags string

Route flags.

]

facts

object

Extended facts from additional providers.

property name* any

Extended facts from additional providers.

state string

Possible values: [Ready, Draining, Cordoned, Pending]

Agent scheduling state.

conditions

object[]

Evaluated node conditions.

Array [

type stringrequired

Possible values: [MemoryPressure, HighLoad, DiskPressure]

status booleanrequired

reason string

last_transition_time date-timerequired

]

timeline

object[]

Agent state transition history.

Array [

timestamp date-timerequired

event stringrequired

hostname string

message string

error string

]

]

total integerrequired

Total number of active agents.

Example (from schema)

{
  "agents": [
    {
      "machine_id": "string",
      "fingerprint": "string",
      "hostname": "string",
      "status": "Ready",
      "labels": {},
      "registered_at": "2024-07-29T15:51:28.071Z",
      "started_at": "2024-07-29T15:51:28.071Z",
      "os_info": {
        "distribution": "Ubuntu",
        "version": "20.04"
      },
      "uptime": "string",
      "load_average": {
        "1min": 0.32,
        "5min": 0.28,
        "15min": 0.25
      },
      "memory": {
        "total": 8388608,
        "free": 2097152,
        "used": 4194304
      },
      "architecture": "amd64",
      "kernel_version": "5.15.0-91-generic",
      "cpu_count": 4,
      "fqdn": "web-01.example.com",
      "service_mgr": "systemd",
      "package_mgr": "apt",
      "interfaces": [
        {
          "name": "eth0",
          "ipv4": "192.168.1.10",
          "ipv6": "fe80::1",
          "mac": "00:11:22:33:44:55",
          "family": "dual"
        }
      ],
      "primary_interface": "eth0",
      "routes": [
        {
          "destination": "0.0.0.0",
          "gateway": "192.168.1.1",
          "interface": "eth0",
          "mask": "/0",
          "metric": 100,
          "flags": "0003"
        }
      ],
      "facts": {},
      "state": "Ready",
      "conditions": [
        {
          "type": "MemoryPressure",
          "status": true,
          "reason": "string",
          "last_transition_time": "2024-07-29T15:51:28.071Z"
        }
      ],
      "timeline": [
        {
          "timestamp": "2024-07-29T15:51:28.071Z",
          "event": "string",
          "hostname": "string",
          "message": "string",
          "error": "string"
        }
      ]
    }
  ],
  "total": 0
}

401

Unauthorized - API key required

application/json

Schema

Schema

error string

A description of the error that occurred.

details string

Additional details about the error.

code integer

The error code.

Example (from schema)

{
  "error": "Failed to retrieve status.",
  "details": "Failed due to network timeout.",
  "code": 500
}

403

Forbidden - Insufficient permissions

application/json

Schema

Schema

error string

A description of the error that occurred.

details string

Additional details about the error.

code integer

The error code.

Example (from schema)

{
  "error": "Failed to retrieve status.",
  "details": "Failed due to network timeout.",
  "code": 500
}

500

Error discovering agents.

application/json

Schema

Schema

error string

A description of the error that occurred.

details string

Additional details about the error.

code integer

The error code.

Example (from schema)

{
  "error": "Failed to retrieve status.",
  "details": "Failed due to network timeout.",
  "code": 500
}

Loading...