You can call this operation to query the VNC URL of an ECS instance.


When you call this operation, take note of the following points:

  • A VNC URL is only valid for 15 seconds. If a connection is not established within 15 seconds after a successful query, the URL expires and you must query it again.
  • The KeepAlive time of a VNC connection is 60 seconds. If you do not interact with the VNC within 60 seconds, the VNC will be automatically disconnected.
  • When the VNC is disconnected, you can only reconnect to the VNC a maximum of 30 times a minute.
  • You must set vncUrl to xxxx, instanceId to xxx, password to XXXXXX, and isWindows to True or isWindows to False at the end of the URL. Connect multiple parameters with ampersands (&). where:
    • vncUrl: the VncUrl value that is returned after a successful query.
    • instanceId: the ID of your instance.
    • isWindows: specifies whether the operating system of the instance is Windows. If the parameter is set to true, the operating system is Windows. If the value is set to false, the operating system is not Windows.
    • password: Optional. The password for connecting to the instance. It must be six characters in length and can contain digits and letters. You can use this parameter to eliminate the need to enter your password when you connect to the VNC.



OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter Type Required Example Description
Action String Yes DescribeInstanceVncUrl

The operation that you want to perform. If you use a custom HTTP URL or HTTPS URL to make an API request, you must specify the Action parameter. Set the value to DescribeInstanceVncUrl.

InstanceId String Yes i-bp1hzoinajzkh91h****

The ID of the instance.

RegionId String Yes cn-hangzhou

The region ID of the instance. You can call the DescribeRegions operation to query the most recent region list.

Response parameters

Parameter Type Example Description
RequestId String 473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E

The ID of the request.

VncUrl String



Sample requests
&<Common request parameters>

Sample success responses

XML format


JSON format

    "RequestId": "1450F2D7-5435-4420-BBC9-49C5xxxxxxxx",
    "VncUrl": ""

Error codes

HTTP status code Error code Error message Description
404 InvalidRegionId.NotFound The specified RegionId does not exist. The error message returned because the specified RegionId parameter does not exist.
404 InvalidInstanceId.NotFound The specified InstanceId does not exist. The error message returned because the specified InstanceId parameter does not exist. Check whether the instance ID is correct.
403 IncorrectInstanceStatus The current status of the resource does not support this operation. The error message returned because the operation is not supported while the resource is in the current state.
500 InternalError The request processing has failed due to some unknown error. The error message returned because an internal error has occurred. Try again later. If the problem persists, submit a ticket.
403 InstanceNotReady The specified instance is not ready for use The error message returned because the specified instance cannot be connected for the moment. Try again later.
400 InvalidRegionInstance The specified InstanceId does not exist in given region. The error message returned because the instance does not exist in the specified region. Check whether the RegionId and InstanceId parameters are correct.

For a list of error codes, visit the API Error Center.