Skip to content
perstatDocs

List agents of an organization

GET
/organizations/{org_id}/agents
curl --request GET \
  --url https://api.perstat.io/organizations/example/agents \
  --header 'Authorization: Bearer <token>'

Returns the enrolled agents of the organization with hostname, platform, version, online state, last heartbeat, and the latest CPU, memory, and disk readings. Each entry also carries monitor_count, the number of active monitors bound to that agent, which are the monitors that would be archived if the agent were removed. Any organization member may read the list. Accepts API keys with the agents:read scope, subject to current role and resource grants.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
org_id
required
string

Responses

Section titled “Responses”

200

Section titled “200”

Request succeeded. The response body contains the result.

Media typeapplication/json
Array<object>
object
agent_version
required
string
arch
required
string
enrolled_at_unix
required
integer format: int64
hostname
required
string
id
required
string
inventory_enabled
required

Opt-in: Prozessnamen-Inventar übertragen (erweiterte Konfiguration).

boolean
labels
required
last_cpu_pct
number | null format: double
last_disk_pct
number | null format: double
last_heartbeat_at_unix
integer | null format: int64
last_mem_pct
number | null format: double
latest_version
required

Neueste verfügbare Agent-Version (für „Update verfügbar“-Hinweis).

string
modules
required
Array<string>
monitor_count
required

Aktive Monitore, die auf diesen Agenten zeigen. Der Entfernen-Dialog muss VOR dem Klick sagen können, wie viele davon mit archiviert werden (siehe revoke_agent) — „N Monitore verschwinden gleich mit“ ist keine Nachricht, die man erst hinterher bekommen darf.

integer format: int64
online
required

Heartbeat jünger als 180 s (3× Push-Intervall) → online.

boolean
os
required
string
outdated
required

Agent-Version liegt hinter latest_version.

boolean
platform
string | null
process_inventory

Zuletzt übertragenes Inventar (nur Prozessnamen) + Zeitpunkt; fürs Transparenz-Panel und die Vorschläge im Dienst-Monitor-Formular.

Array<string> | null
process_inventory_at_unix
integer | null format: int64
Examplegenerated
[
  {
    "agent_version": "example",
    "arch": "example",
    "enrolled_at_unix": 1,
    "hostname": "example",
    "id": "example",
    "inventory_enabled": true,
    "labels": "example",
    "last_cpu_pct": 1,
    "last_disk_pct": 1,
    "last_heartbeat_at_unix": 1,
    "last_mem_pct": 1,
    "latest_version": "example",
    "modules": [
      "example"
    ],
    "monitor_count": 1,
    "online": true,
    "os": "example",
    "outdated": true,
    "platform": "example",
    "process_inventory": [
      "example"
    ],
    "process_inventory_at_unix": 1
  }
]

401

Section titled “401”

Authentication is missing or invalid.

403

Section titled “403”

The authenticated caller does not have permission to perform this operation.

404

Section titled “404”

No accessible resource matches the supplied identifier.