NSX-T Data Center REST API

Returns the list of all virtual machines created or imported under a particular account id. Supports optional query parameters like region id, vpc id, public_ip, is_gateway.

Request:

Method:

GET

URI Path(s):

/api/v1/csm/virtual-machines

Request Headers:

n/a

Query Parameters:

CloudVirtualMachinesListRequestParameters+

CloudVirtualMachinesListRequestParameters (schema)

Name	Description	Type	Notes
account_id	Account ID Optional identifier for account based on which virtual machines are to be filtered	string
agent_status	Agent Status UP - NSX Agent is up and running DOWN - NSX Agent is down NO_AGENT - No NSX Agent installed on instance UNKNOWN - NSX Agent status is unknown UPDATE_AVAILABLE - NSX Tools can be upgraded to a newer version that's available NEEDS_UPDATE - NSX Tools running on the instance needs to be updated for proper functioning	string	Readonly Enum: UP, DOWN, NO_AGENT, UNKNOWN, UPDATE_AVAILABLE, NEEDS_UPDATE
cloud_security_group_id	Security Group ID Optional identifier to limit results of VMs associated with the provided cloud security group. For AWS, provide the group id. For Azure, provide the resourceGuid of the Azure security group.	string	Readonly
cloud_type	Cloud Type Optional identifier for cloud provider based on which Virtual Machines are to be filtered	string	Enum: AWS, AZURE
cursor	Opaque cursor to be used for getting next page of records (supplied by current result page)	string
included_fields	Comma separated list of fields that should be included in query result Note - this parameter currently only works when used with the search APIs /policy/api/v1/search/query and /policy/api/v1/search/dsl. It is ignored for other list APIs.	string
instance_id	Instance ID Optional identifier for virtual machine based on which the list can be filtered	string
is_gateway	Is the VM a gateway node? Optional identifier based on which only gateway Virtual Machines can be filtered	boolean
logical_switch_id	Logical Switch ID Optional identifier for logical switch based on which Aws Virtual Machines are to be filtered	string
page_size	Maximum number of results to return in this page (server may return fewer)	integer	Minimum: 0 Maximum: 1000 Default: "1000"
public_ip	Public IP address of the virtual machine Optional identifier for public IP based on which Virtual Machines are to be filtered	string
quarantine_state	Quarantine State Identifier for quarantine state based on which Virtual Machines are to be filtered. QUARANTINED - This state implies instance is moved to quarantine security group because some threat has been detected. NOT_QUARANTINED - This state implies no quarantine action has been taken. UNKNOWN - This state implies either quarantine policy is disabled or quarantine information is not available. OVERRIDDEN - This state implies instance is associated with vm_override_sg which overrides any action based on threat detection.	string	Readonly Enum: QUARANTINED, NOT_QUARANTINED, UNKNOWN, OVERRIDDEN
region_id	Region ID Optional identifier for AWS or Azure region based on which Virtual Machines are to be filtered	string
resource_type	Resource Type Optional identifier for listing virtual machines of a particular cloud provider. Possible values are in the form of VirtualMachine prefixed by cloud name. For example, AwsVirtualMachine or AzureVirtualMachine.	string	Enum: AwsVirtualMachine, AzureVirtualMachine
segment_id	Segment ID Optional identifier for segment based on which Virtual Machines are to be filtered.	string
sort_ascending		boolean
sort_by	Field by which records are sorted	string
status_filter	Filter by Virtual machine status POWERED_OFF - Powered off instances. MANAGED - Instances that are managed by NSX or tagged. UNMANAGED - Instances that are not managed by NSX or untagged. ERRORED - Instances with no NSX Tools connectivity, NSX Tools is down, No NSX Policy configured for Native cloud security enforced instances or Error on NSX Policy rule realization. WHITELISTED - Instances which have been marked allowed by NSX [DEPRECATED - replaced with USERMANAGED]. USERMANAGED - Instances which have been marked allowed by NSX. QUARANTINED - Instances that have been quarantined because some threat has been detected. NEEDS_UPDATE - NSX Tools running on instance is out of date and needs to be updated. HORIZON_VDI - Instances on Microsoft Azure that are part of the Horizon Cloud Services (HCS).	string	Readonly Enum: POWERED_OFF, MANAGED, UNMANAGED, ERRORED, WHITELISTED, USERMANAGED, QUARANTINED, NEEDS_UPDATE, HORIZON_VDI
vnet_id	Azure virtual network ID Optional identifier for Azure virtual network based on which Azure Virtual Machines are to be filtered. It consists of resourceGuid of Azure Vnet.	string
vpc_id	AWS VPC ID Optional identifier for AWS VPC based on which Virtual Machines are to be filtered	string

Request Body:

n/a

Example Request:

GET https://<nsx-csm>/api/v1/csm/virtual-machines

Successful Response:

Response Code:

200 OK

Response Headers:

Content-type: application/json

Response Body:

CloudVirtualMachinesListResult+

CloudVirtualMachinesListResult (schema)

Name	Description	Type	Notes
_links	References related to this resource The server will populate this field when returing the resource. Ignored on PUT and POST.	array of ResourceLink	Readonly
_schema	Schema for this resource	string	Readonly
_self	Link to this resource	SelfResourceLink	Readonly
cursor	Opaque cursor to be used for getting next page of records (supplied by current result page)	string	Readonly
result_count	Count of results found (across all pages), set only on first page	integer	Readonly
results	Results Array of cloud virtual machines	array of CloudVirtualMachine (Abstract type: pass one of the following concrete types) AwsVirtualMachine AzureVirtualMachine CloudVirtualMachine
sort_ascending	If true, results are sorted in ascending order	boolean	Readonly
sort_by	Field by which records are sorted	string	Readonly

Example Response:

{ "cursor": "0003348", "sort_ascending": true, "result_count": 348, "results": [ { "description": "t2.micro", "id": "i-027c0b32cbe631ec9", "display_name": "vm-2", "is_gateway": false, "private_ip": "13.14.41.253", "cloud_tags": [], "os_type": "AMAZON_LINUX", "agent_status": "NO_AGENT", "os_details": "", "availability_zone": "us-west-2c", "vpc": "vpc-f4ddaf93", "vm_config_status": { "whitelist": { "whitelisted": "YES" }, "usermanaged": { "usermanaged": "YES" } }, "nsx_successful_rules_count" : 1, "nsx_failed_rules_count" : 0 }, { "region": "westus", "vnet": "7f3e9fce-8e92-407f-ad82-02c26dd566f1", "vnet_name": "nsx-vpn-vnet-01", "resource_group": "UBUNTU-VM-01-RG", "power_state": "STOPPED", "resource_id": "/58bbb0ce-e26a-4bbc-a49c-284f63c25e2e/resourceGroups/UBUNTU-VM-01-RG/providers/Microsoft.Compute/virtualMachines/ubuntu-vm-01", "resource_type": "AzureVirtualMachine", "id": "5735faab-4751-4e25-8db7-78f6a35b7e42", "display_name": "ubuntu-vm-01", "os_type": "Linux", "cloud_tags": [], "public_ip": "52.160.36.45", "private_ip": "22.22.4.5", "is_gateway": false, "managed_by_nsx": true, "quarantine_state": "UNKNOWN", "threat_state": "INVALID", "nsx_security_rule_errors_count": 0, "nsx_security_rule_errors": [], "status": "POWERED_OFF", "agent_status": "UPDATE_AVAILABLE", "cloud_instance_type": "HORIZON_VDI", "associated_account_ids": [ "877b27fe-5935-4a09-8c25-f3df9afd326b" ], "vm_config_status": { "whitelist": { "whitelisted": "NO" }, "usermanaged": { "usermanaged": "NO" } }, "nsx_successful_rules_count": 0, "nsx_failed_rules_count": 0 }, { "description": "c4.xlarge", "id": "i-0b62834659a30fc21", "display_name": "nsx-gw-vpc-c35dbaa4-preferred-active", "public_ip": "52.89.33.233", "is_gateway": true, "private_ip": "10.0.1.97", "is_gateway_active": true, "cloud_tags": [], "gateway_status": "UP", "os_type": "UBUNTU", "os_details": "LTS 14.04", "availability_zone": "us-west-2a", "vpc": "vpc-c35dbaa4", "vm_config_status": { "whitelist": { "whitelisted": "NO" } "usermanaged": { "usermanaged": "NO" } }, "nsx_successful_rules_count" : 1, "nsx_failed_rules_count" : 0 } ] }

Required Permissions:

read

Feature:

cloud_resources

Additional Errors:

• 301 Moved Permanently
• 307 Temporary Redirect
• 400 Bad Request
• 403 Forbidden
• 409 Conflict
• 412 Precondition Failed
• 500 Internal Server Error
• 503 Service Unavailable