Per-instance in-VM agent state across every project.

GET

/v1/admin/compute/instance-agents

Code sample: Shell / cURL

curl --request GET \
  --url https://stratum.example.com/v1/admin/compute/instance-agents \
  --header 'Authorization: Bearer <token>'

• A Stratum cluster endpoint.

Operator endpoint. The drill-in behind the fleet summary: one row per live instance, in every project, with its agent version, health and last heartbeat.

Instances whose agent has never reported ARE included, with health: unknown and no version. They are the population an operator is usually looking for, so omitting them would defeat the purpose.

Install-scoped, like the other /v1/admin/compute/* endpoints.

Authorizations

• bearerAuth

Responses

200

Per-instance agent state.

Media typeapplication/json

object

servedVersion

required

The agent build this control plane serves, repeated here so a client rendering the list does not need the summary call too.

string

items

required

Array<object>

One instance’s in-VM agent state in the fleet listing.

object

projectId

required

Owning project. The listing spans all of them.

string

instanceId

required

string

instanceName

required

string

agentVersion

Build the agent reported. Absent when it has never reported, which is the same condition as health: unknown.

string

health

required

Same derivation as the per-instance agent-status endpoint: unknown when the agent has never reported, unhealthy when it has been silent longer than the heartbeat window, agent_disabled when the instance does not want an agent and enrollment_pending when it was enabled and not yet installed.

string

Allowed values: healthy unhealthy unknown agent_disabled enrollment_pending

lastSeen

Last heartbeat. Absent when the agent has never reported.

string format: date-time

onServedVersion

required

Whether agentVersion matches the build the control plane serves. True when either side is unknown, so missing metadata never reads as drift.

boolean

Example

{
  "items": [
    {
      "health": "healthy"
    }
  ]
}

403

Authenticated but not authorized.

Media typeapplication/problem+json

object

type

required

string format: uri

title

required

string

status

required

integer

>= 400 <= 599

detail

string

instance

string format: uri-reference

requestId

required

string

code

required

string

issues

The findings of a rejected IAM policy document (custom and resource policies).

Array<object>

One finding of a rejected IAM policy document. A rejection lists every finding, so the author fixes the document in one round trip.

object

code

required

The finding, e.g. INVALID_DOCUMENT, UNKNOWN_ACTION, ACTION_NOT_APPLICABLE.

string

statement

required

Index of the statement at fault; -1 for the document as a whole.

integer

>= -1

detail

required

string

action

The offending action, where one is at fault (ACTION_NOT_APPLICABLE).

string

errors

Field errors, for codes that carry them: each problem at its field (see FieldError). Documented on the responses that set it, e.g. approveNodeJoin’s INVALID_INPUT and JOIN_APPROVAL_REFUSED. Absent otherwise.

Array<object>

One field’s problem, the stage-2 installer API’s shape. field is the field’s path, message what is wrong with it.

object

field

required

The field’s path, e.g. links[0].interface, disks[1].confirm, mgmt.address or role; empty for the whole request.

string

message

required

string

details

Structured facts about the refusal, for codes that carry them. The shape is fixed per code and documented on the response that answers it, e.g. IMAGE_POOL_MISMATCH (see ImagePoolMismatchDetails) and IMAGE_IN_USE. Absent for codes that carry none.

object

key

additional properties

any

Example

{
  "issues": [
    {
      "code": "ACTION_NOT_APPLICABLE",
      "action": "compute:CreateVpc"
    }
  ]
}