Endpoints Operations List
Returns a paginated collection of endpoint summaries matching query criteria. Accessible to every authenticated role.
Zero-based page index (default 0). A negative page answers 400 INVALID_PAGINATION; it is not clamped.
Number of items per page (default 20, 1 to 100). A value outside 1 to 100 answers 400 INVALID_PAGINATION; it is not clamped.
20
Case-insensitive substring search matching hostname or IP address
esx02.example.com
Filter by communication status: ONLINE, OFFLINE, or NOT_REPORTING for endpoints that have not reported any state yet. A comma-separated list matches any of its values, for example OFFLINE,NOT_REPORTING. Omit for no filtering. Upper-case values are the contract; the server also accepts any letter case.
OFFLINE,NOT_REPORTING
Filter by lifecycle state (ACTIVE, OFFLINE, DELETED)
ACTIVE
Filter by associated security group ID
1
Leave out the endpoints that belong to this security group ID, so a caller picking endpoints to add to a group pages through only those that are not already members (VTPSECA-495). Combines with every other filter by AND; omit for no exclusion.
2
CURRENT lists only Agents linked to a host in the current inventory; NOT_CURRENT lists only Agents with no such host (historical identities whose release this Console has not confirmed). Omit to list every Agent (the default, unchanged). Nothing is matched by IP address or hardware UUID.
CURRENT
Filter by policy synchronization state (GOOD, PENDING, ERROR), or NOT_REPORTING for endpoints that have not reported any state yet. A comma-separated list matches any of its values, for example PENDING,ERROR,NOT_REPORTING. A concrete state never matches an endpoint with no reported state unless NOT_REPORTING is also listed. The commStatus and policySyncState filters are combined with AND. Omit for no filtering. Upper-case values are the contract; the server also accepts any letter case.
PENDING,ERROR,NOT_REPORTING
Field to sort by (default: hostname)
hostname
Sort direction (default: ASC)
ASC
200 OK successful response envelope. A page of endpoint summaries that match the filters
{
"items": [
{
"id": "2",
"hostname": "esx02.example.com",
"ipAddress": "192.0.2.12",
"macAddress": "00:00:5e:00:53:02",
"agentVersion": "1.4.2",
"inventoryAssociation": "CURRENT",
"esxiVersion": "8.0.2",
"lifecycleState": "ACTIVE",
"commStatus": "ONLINE",
"healthStatus": "OK",
"policySyncState": "GOOD",
"appliedPolicyVersion": 3,
"agentDisabledStatus": false,
"groupId": "1",
"groupName": "Production Servers",
"enforcementMode": "ENFORCE",
"lastHeartbeatAt": "2026-01-15T09:29:30Z",
"registeredAt": "2026-01-12T10:15:00Z"
},
{
"id": "4",
"hostname": "esx04.example.com",
"ipAddress": "192.0.2.14",
"macAddress": "00:00:5e:00:53:04",
"agentVersion": "1.4.2",
"inventoryAssociation": "NOT_CURRENT",
"esxiVersion": "8.0.2",
"lifecycleState": "ACTIVE",
"commStatus": "OFFLINE",
"healthStatus": "OK",
"policySyncState": "GOOD",
"appliedPolicyVersion": 3,
"agentDisabledStatus": false,
"groupId": "1",
"groupName": "Production Servers",
"enforcementMode": "ENFORCE",
"lastHeartbeatAt": "2026-01-14T09:30:00Z",
"registeredAt": "2026-01-12T10:15:00Z"
}
],
"page": 0,
"pageSize": 25,
"totalItems": 2,
"totalPages": 1
}
Array of items for the current page
Zero-based current page number
Number of items requested per page
Total number of items matching filter criteria
Total number of available pages
400 Bad Request: INVALID_PAGINATION when page is negative or pageSize is outside 1 to 100; INVALID_FILTER when commStatus, lifecycleState, policySyncState, groupId or enforcementMode is not a valid value; INVALID_SORT when sortBy is not a sortable property or sortOrder is not ASC or DESC
{
"errorCode": "string",
"message": "string",
"path": "string",
"timestamp": "string",
"reason": "string"
}
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.
Human-readable error description
Request URI path that produced the error
Timestamp when the error occurred as an ISO 8601 date-time with offset
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 Unauthorized: UNAUTHENTICATED when the VTP_SESSION cookie is missing, unknown, expired or revoked
{
"errorCode": "string",
"message": "string",
"path": "string",
"timestamp": "string",
"reason": "string"
}
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.
Human-readable error description
Request URI path that produced the error
Timestamp when the error occurred as an ISO 8601 date-time with offset
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 Internal Server Error: INTERNAL_ERROR when the server fails unexpectedly; the message carries no detail
"ApiErrorResponse Object"
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.
Human-readable error description
Request URI path that produced the error
Timestamp when the error occurred as an ISO 8601 date-time with offset
A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.
curl -H 'Authorization: <value>' https://{api_host}/api/v1/endpoints