Request Syntax URI Request Parameters Request Body Response Syntax Response Elements Errors See Also

GetConnection

Retrieves connection information for the specified MQTT client.

Requires permission to access the GetConnection action.

Request Syntax


GET /connections/clientId?includeSocketInformation=includeSocketInformation HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

clientId

The unique identifier of the MQTT client to retrieve connection information. The client ID can't start with a dollar sign ($).

MQTT client IDs must be URL encoded (percent-encoded) when they contain characters that are not valid in HTTP requests, such as spaces, forward slashes (/), and UTF-8 characters.

Length Constraints: Minimum length of 1. Maximum length of 128.

Pattern: ^[^$].*

Required: Yes

includeSocketInformation

Specifies if socket information (sourcePort, targetPort, sourceIp, targetIp) should be included in the GetConnection response. Set to TRUE to include socket information. Set to FALSE to omit socket information. By default, this is set to FALSE. See the developer guide for how to authorize this parameter.

Request Body

The request does not have a request body.

Response Syntax


HTTP/1.1 200
Content-type: application/json

{
   "cleanSession": boolean,
   "clientId": "string",
   "connected": boolean,
   "connectedSince": number,
   "disconnectedSince": number,
   "disconnectReason": "string",
   "keepAliveDuration": number,
   "sessionExpiry": number,
   "sourceIp": "string",
   "sourcePort": number,
   "targetIp": "string",
   "targetPort": number,
   "thingName": "string",
   "vpcEndpointId": "string"
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

cleanSession

Indicates whether the client is using a clean session. Returns true for clean sessions or false for persistent sessions.

Type: Boolean

clientId

The unique identifier of the MQTT client. This is the same client ID that was used when the client established the connection.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 128.

Pattern: ^[^$].*

connected

The connection state of the client. Returns true if the client is currently connected, or false if the client is not connected.

Type: Boolean

connectedSince

Unix timestamp (in milliseconds) indicating when the client connected. Present only when connected is true.

Type: Long

disconnectedSince

Unix timestamp (in milliseconds) indicating when the client disconnected. Present only when connected is false. This information is available for 30 minutes after the client disconnects.

Type: Long

disconnectReason

The reason for the last disconnection, if the client is currently disconnected. See the developer guide for valid disconnect reasons.

Type: String

keepAliveDuration

The keep-alive interval in seconds that the client specified when establishing the connection.

Type: Integer

sessionExpiry

The session expiry interval in seconds for the MQTT client connection. This is configured by the user. This value indicates how long the session will remain active after the client disconnects.

Type: Long

sourceIp

The IP address of the client that initiated the connection.

Type: String

sourcePort

The client's source port.

Type: Integer

targetIp

The IP address of the AWS IoT Core endpoint that the client connected to. For clients connected to VPC endpoints, this is the private IP address of the network interface the client is connected to.

Type: String

targetPort

The port number of the AWS IoT Core endpoint that the client connected to.

Type: Integer

thingName

The name of the thing associated with the principal of the MQTT client, if applicable.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 128.

Pattern: [a-zA-Z0-9:_-]+

vpcEndpointId

The ID of the VPC endpoint. Present for clients connected to IoT Core via a VPC endpoint.

Type: String

Errors

ForbiddenException

The caller isn't authorized to make the request.

HTTP Status Code: 403

InternalFailureException

An unexpected error has occurred.

message: The message for the exception.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

message: The message for the exception.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

message: The message for the exception.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

message: The message for the exception.

HTTP Status Code: 429