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

GetThingConnectivityData

Retrieves the live connectivity status per device. If a device has never connected to IoT Core or was disconnected for more than 1 hour before fleet indexing's thingConnectivityIndexingMode was enabled, the response will have the connected field set to false with no additional session details.

Request Syntax


POST /things/thingName/connectivity-data HTTP/1.1
Content-type: application/json

{
   "includeSocketInformation": boolean
}

URI Request Parameters

The request uses the following URI parameters.

thingName

The name of your IoT thing.

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

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

Required: Yes

Request Body

The request accepts the following data in JSON format.

includeSocketInformation

Specifies if socket information (sourcePort, targetPort, sourceIp, targetIp, vpcEndpointId) should be included in the GetThingConnectivityData response. Set to true to include socket information. Set to false to omit socket information. By default, this is set to false.

Type: Boolean

Required: No

Response Syntax


HTTP/1.1 200
Content-type: application/json

{
   "cleanSession": boolean,
   "clientId": "string",
   "connected": boolean,
   "disconnectReason": "string",
   "keepAliveDuration": number,
   "sessionExpiry": number,
   "sourceIp": "string",
   "sourcePort": number,
   "targetIp": "string",
   "targetPort": number,
   "thingName": "string",
   "timestamp": number,
   "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.

Type: Boolean

clientId

The unique identifier of the MQTT client.

Type: String

connected

A Boolean that indicates the connectivity status.

Type: Boolean

disconnectReason

The reason that the client is disconnected.

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 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.

Type: String

targetPort

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

Type: Integer

thingName

The name of your IoT thing.

Type: String

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

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

timestamp

The timestamp of when the device connected or disconnected.

Type: Timestamp

vpcEndpointId

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

Type: String

Errors

IndexNotReadyException

The index is not ready.

message: The message for the exception.

HTTP Status Code: 400

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

ServiceUnavailableException

The service is temporarily unavailable.

message: The message for the exception.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

message: The message for the exception.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

message: The message for the exception.

HTTP Status Code: 401