Endpoints Operations Get By Id

Endpoints Operations Get By Id
Get detailed information for a single endpoint by ID

Returns full operational, inventory, policy, and health detail for the endpoint. Accessible to every authenticated role.

Request
URI
GET
https://{api_host}/api/v1/endpoints/{id}
COPY
Path Parameters
string
id
Required  

Unique external endpoint identifier (string-serialized 64-bit integer)

id example
2

Authentication
This operation uses the following authentication methods.
Responses
200

200 OK successful response envelope. The endpoint detail

Returns EndpointDetail of type(s) application/json
{
    "id": "2",
    "hostname": "esx02.example.com",
    "ipAddress": "192.0.2.12",
    "macAddress": "00:00:5e:00:53:02",
    "esxiVersion": "8.0.2",
    "esxiBuild": "20000000",
    "agentVersion": "1.4.2",
    "lifecycleState": "ACTIVE",
    "commStatus": "ONLINE",
    "healthStatus": "OK",
    "policySyncState": "GOOD",
    "appliedPolicyVersion": 3,
    "agentDisabledStatus": false,
    "policyErrorCode": null,
    "policyErrorDetail": null,
    "failedRuleRef": null,
    "policyAppliedAt": "2026-01-15T09:20:00Z",
    "lastHeartbeatAt": "2026-01-15T09:29:30Z",
    "missedHeartbeats": 0,
    "groupId": "1",
    "groupName": "Production Servers",
    "enforcementMode": "ENFORCE",
    "heartbeatIntervalSeconds": 300,
    "eventsDropped": 0,
    "spoolBytesUsed": 0,
    "cpuPercent": 37,
    "memoryPercent": 62,
    "registeredAt": "2026-01-12T10:15:00Z",
    "updatedAt": "2026-01-15T09:29:30Z",
    "mfaVault": {
        "state": "NOT_REQUIRED",
        "version": null,
        "credentialCount": null,
        "detail": null,
        "updatedAt": "2026-01-15T09:20:00Z"
    }
}
string
id
Required  

Unique external endpoint identifier (string-serialized 64-bit ID)

string
hostname
Required  

Host name recorded for the endpoint's agent

string
ipAddress
Optional

Primary IP address of the endpoint

string
macAddress
Optional

Primary MAC address of the endpoint

string
esxiVersion
Optional

Host ESXi hypervisor version

string
esxiBuild
Optional

Host ESXi build number/string

string
agentVersion
Optional

Installed VTP agent version

string
lifecycleState
Required  

Administrative lifecycle state of the endpoint

  • ACTIVE: The endpoint is registered and has heartbeated; the default stored state, also set again by the next heartbeat of an OFFLINE endpoint
  • OFFLINE: The state stored when the endpoint is enrolled, until its first heartbeat
  • DELETED: The endpoint was retired by the Console; a retired endpoint no longer counts toward catalogued files' host counts
Enumeration: ACTIVE, OFFLINE, DELETED
commStatus
Optional

Communication status recorded for the agent; set ONLINE by each heartbeat and OFFLINE by the Console when the host is marked offline; null when no agent state exists

healthStatus
Optional

Agent health taken from the status the agent reported in its last heartbeat; null when no agent state exists

policySyncState
Optional

Whether the agent holds the policy of its current Security Group; null when no agent state exists, which is the Not reporting set that the policySyncState=NOT_REPORTING list filter returns

integer As int64 As int64
appliedPolicyVersion
Optional

Policy version of the Security Group the agent last reported as applied, as recorded by the rules sync; null when no agent state exists

boolean
agentDisabledStatus
Optional

Whether this endpoint's agent is currently in the dormant "circuit breaker" state (rule evaluation unhooked entirely)

string
policyErrorCode
Optional

Error code if policy application failed

string
policyErrorDetail
Optional

Error detail message if policy application failed

string
failedRuleRef
Optional

External reference of rule that failed policy application

string As date-time As date-time
policyAppliedAt
Optional

Timestamp when policy was applied on the endpoint as an ISO 8601 date-time with offset

string As date-time As date-time
lastHeartbeatAt
Optional

Last successful heartbeat timestamp as an ISO 8601 date-time with offset

integer As int32 As int32
missedHeartbeats
Optional

Consecutive missed heartbeat count

string
groupId
Optional

Associated security group identifier

string
groupName
Optional

Associated security group display name

enforcementMode
Optional

Active enforcement mode of the endpoint's assigned Security Group

integer As int32 As int32
heartbeatIntervalSeconds
Optional

Security group configured heartbeat interval in seconds

integer As int64 As int64
eventsDropped
Optional

Count of dropped events reported by agent

integer As int64 As int64
spoolBytesUsed
Optional

Spool storage bytes used on endpoint

number As float As float
cpuPercent
Optional
Constraints: minimum: 0 maximum: 100

CPU utilization percentage reported by agent

number As float As float
memoryPercent
Optional
Constraints: minimum: 0 maximum: 100

Memory utilization percentage reported by agent

string As date-time As date-time
registeredAt
Required  

Timestamp when the endpoint first registered as an ISO 8601 date-time with offset

string As date-time As date-time
updatedAt
Required  

Timestamp when the endpoint record was last updated as an ISO 8601 date-time with offset

object
mfaVault
Optional

Applied status of the SSH MFA vault. The detail is a reason code or the Agent's truncated failure text and never contains secret material. Null only when no AgentState row exists yet.


400

400 Bad Request: INVALID_ENDPOINT_ID when the id is blank or is not a number

Returns ApiErrorResponse of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.


401

401 Unauthorized: UNAUTHENTICATED when the VTP_SESSION cookie is missing, unknown, expired or revoked

Returns Unauthenticated of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.


404

404 Not Found: ENDPOINT_NOT_FOUND when no endpoint has the id

Returns ApiErrorResponse of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.


500

500 Internal Server Error: INTERNAL_ERROR when the server fails unexpectedly; the message carries no detail

Returns InternalError of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.


Code Samples
COPY
                    curl -H 'Authorization: <value>' https://{api_host}/api/v1/endpoints/{id}