ListManagedAgents

List Agents within agent.read scope grants using limit/offset and a numeric total. Defaults to active and revoking; revoked requires explicit selection. Keyword searches display name, Agent ID, host name and IP addresses. Sort accepts displayName, createdAt or lastHeartbeatAt; order accepts asc or desc. All filters, including certified upgrade availability, apply before counting and pagination in one database read view. Continuity uses cached observations with their original timestamps and never triggers a metric query.

GET/api/v1/lifecycle/managed-agent/agents

Operation ID

ListManagedAgents

Since

1.3.0

Execution Mode

Synchronous

Auth Context

Auth Required

Auth Context

Send these values as request headers when calling this API.

AuthorizationstringRequired

Bearer Token

X-Tenant-IDstring

X-Tenant-ID

Request Inputs

Query Parameters

platformUuid
String
Filter by the associated platform UUID
regionUuid
String
Filter by the associated region UUID
accessState
String
Filter by the current access state
primaryStatus
String
Filter by the primary runtime status
capabilityId
String
Filter by a supported capability identifier

Responses

200 OK

On success, this API returns the following response structure.

items
List
Collection of result items
Example: (nested array)
- agentId
  String
  Agent id for this resource
  Example: value
- displayName
  String
  Display name for this resource
  Example: value
- scope
  Object
  Scope for this resource
  platformUuid
  String
  Platform uuid for this resource
  Example: value
  regionUuid
  String
  Region uuid for this resource
  Example: value
- agentVersion
  String
  Agent version for this resource
  Example: value
- accessState
  String
  Access state for this resource
  Example: value
- healthStatus
  String
  Health status for this resource
  Example: value
- runtimeState
  String
  Runtime state for this resource
  Example: value
- primaryStatus
  String
  Primary status for this resource
  Example: value
- lastHeartbeatAt
  String
  Last heartbeat at for this resource
  Example: 2026-01-15T08:00:00Z
- lastStatusChangedAt
  String
  Last status changed at for this resource
  Example: 2026-01-15T08:00:00Z
- rowVersion
  String
  Row version for this resource
  Example: 10
- capabilities
  List
  Capabilities for this resource
  Example: (nested array)
  capabilityId
  String
  Capability id for this resource
  Example: value
  displayName
  String
  Display name for this resource
  Example: value
  available
  Boolean
  Available for this resource
  Example: true
  blockedBy
  List
  Blocked by for this resource
  Example: item1,item2
  bindingId
  String
  Absent before this capability has a persisted Binding.
  Example: value
  desiredState
  String
  Desired state for this resource
  Example: value
  effectiveState
  String
  Effective state for this resource
  Example: value
  providerId
  String
  Provider id for this resource
  Example: value
  providerRevision
  String
  Provider revision for this resource
  Example: value
  currentConfigRevision
  String
  Current config revision for this resource
  Example: 10
  effectiveConfigRevision
  String
  Effective config revision for this resource
  Example: 10
  rowVersion
  String
  Row version for this resource
  Example: 10
  lastObservedAt
  String
  Last observed at for this resource
  Example: 2026-01-15T08:00:00Z
  lastErrorReason
  String
  Last error reason for this resource
  Example: value
  hostMetricContinuitySummary
  Object
  Host metric continuity summary for this resource
  lastHostMetricAt
  String
  Last host metric at for this resource
  Example: 2026-01-15T08:00:00Z
  collectionState
  String
  collecting, stopped or unknown; independent of business sample age.
  Example: value
  deliveryState
  String
  current, delayed, backfilling or unknown; never an exact data gap.
  Example: value
  queueSize
  Long
  Upstream queue units, not a count of metric samples or bytes.
  Example: 0
  queueCapacity
  Long
  Queue capacity for this resource
  Example: 0
  enqueueFailedMetricPoints
  Long
  Enqueue failed metric points for this resource
  Example: 0
  sendFailedMetricPoints
  Long
  Send failed metric points for this resource
  Example: 0
  sentMetricPoints
  Long
  Sent metric points for this resource
  Example: 0
  serviceInstanceId
  String
  Service instance id for this resource
  Example: value
  observedAt
  String
  Observed at for this resource
  Example: 2026-01-15T08:00:00Z
- latestTask
  Object
  Latest task for this resource
  taskId
  String
  Task id for this resource
  Example: value
  type
  String
  Business operation represented by the referenced Agent task: deploy, change_capabilities, enable_capability, update_capability, disable_capability, restart_runtime, upgrade, renew_certificate, or revoke_access.
  Example: value
  state
  String
  State for this resource
  Example: value
  bindingId
  String
  Binding id for this resource
  Example: value
  createdAt
  String
  Created at for this resource
  Example: 2026-01-15T08:00:00Z
  startedAt
  String
  Started at for this resource
  Example: 2026-01-15T08:00:00Z
  completedAt
  String
  Completed at for this resource
  Example: 2026-01-15T08:00:00Z
  errorReason
  String
  Saved, sanitized task errors; never inferred from Agent primary status.
  Example: value
  errorMessage
  String
  Error message for this resource
  Example: value
  availableActions
  List
  Computed from current task facts and caller permissions, not persisted.
  Example: item1,item2
  waitingReason
  String
  Waiting reason for this resource
  Example: value
- updateAvailable
  Boolean
  Static certified-target availability does not authorize Upgrade now.
  Example: true
- targetAgentVersion
  String
  Target agent version for this resource
  Example: value
- createdAt
  String
  Created at for this resource
  Example: 2026-01-15T08:00:00Z
- updatedAt
  String
  Updated at for this resource
  Example: 2026-01-15T08:00:00Z
- hostName
  String
  Host name for this resource
  Example: value
- ipAddresses
  List
  Ip addresses for this resource
  Example: item1,item2
- hostInfoObservedAt
  String
  Host info observed at for this resource
  Example: 2026-01-15T08:00:00Z
- platformName
  String
  Platform name for this resource
  Example: value
- regionName
  String
  Region name for this resource
  Example: value
- productType
  String
  Product type for this resource
  Example: value
- statusReasons
  List
  Status reasons for this resource
  Example: (nested array)
  source
  String
  Source for this resource
  Example: value
  value
  String
  Value for this resource
  Example: value
  taskId
  String
  Task id for this resource
  Example: value
- recommendedActions
  List
  Presentation hints only; never grant permission or replace a precheck.
  Example: item1,item2
- agentRelease
  String
  Agent release for this resource
  Example: 10
- targetAgentRelease
  String
  Target agent release for this resource
  Example: 10
total
Integer
Authorized and filtered count before pagination, encoded as a JSON number.
Example: 10
limit
Integer
Limit for this resource
Example: 10
offset
Integer
Offset for this resource
Example: 10

Request Example

curl -X GET '{host}/api/v1/lifecycle/managed-agent/agents?platformUuid={platformUuid}&regionUuid={regionUuid}&accessState={accessState}&primaryStatus={primaryStatus}&capabilityId={capabilityId}&updateAvailable=true&latestTaskState={latestTaskState}&keyword={keyword}&limit=0&offset=0&sort={sort}&order={order}&hasPlatform=true&hasRegion=true' \
  -H 'Authorization: Bearer {token}'

Response Example

{
  "items": [
    {
      "agentId": "value",
      "displayName": "value",
      "scope": {
        "platformUuid": "value",
        "regionUuid": "value"
      },
      "agentVersion": "value",
      "accessState": "value",
      "healthStatus": "value",
      "runtimeState": "value",
      "primaryStatus": "value"
    }
  ],
  "total": 10,
  "limit": 10,
  "offset": 10
}

Change History

View all change history

Change TimeChange SummaryAction

Change Time
2026-09-17
AddedResponse fields agentRelease, targetAgentRelease
View API

Assets

Collects

Infrastructure Misc

Installer

Lifecycle

OTA Upgrade Plans

OTA Versions & Policies

Federation & SSO

Change Management

Lifecycle Upgrade

Alert Rules

Alert Templates

Alert Channels & Integrations

Alert Events

Alert Routing & Policies

Security

ZMetis Audit

Platforms

Platform Federation

Platform Health

Platform Misc

ZMetis Tasks

ListManagedAgents

Auth Context

Request Inputs

Query Parameters

Responses

Change History