List all gateway instances of all gateway groups

GET /api/instances

List all gateway instances of all gateway groups

IAM Action: gateway:GetGatewayInstance, Resource: arn:api7:gateway:gatewaygroup/%s

Parameters

• gateway_group_id (query, string, optional): Gateway group ID.
• order_by (query, string, optional): Index to order gateway instances by.
• status (query, string, optional): The value of the instance status.
• compatibility (query, string, optional): The compatibility of the gateway instance version.
• direction (query, string, optional): Order to list the resources by. The sorting index follows the configuration of order_by.
• page_size (query, integer, optional): Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.
• page (query, integer, optional): Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.
• search (query, string, optional): Condition to search resources by.

Responses

• 200: Successfully retrieved the paginated list of gateway instances.
• allOf variant 1
• list (array, optional): An array of resources.
• total (integer, optional): Total number of objects.
• allOf variant 2
• list (array, optional): An array of gateway instances.
• list[].id (string, required): The gateway instance ID.
• list[].hostname (string, required): The hostname of the gateway instance.
• list[].ip (string, optional): The IP address of the gateway instance.
• list[].gateway_group_id (string, optional): The gateway group ID.
• list[].version (string, required): The version of the gateway instance.
• list[].ports (array, required): The listening ports of the gateway instance.
• list[].last_heartbeat_time (integer, required): The time of the gateway instance's last heartbeat.
• list[].last_retrieve_config_time (integer, optional): The time when the gateway instance last received its configuration.
• list[].to_be_deleted_at (integer,null, optional): The time to delete offline instances from the instance list.
• list[].created_at (integer, required): The time of the gateway instance's first heartbeat.
• list[].dataplane_certificate_expire_time (integer,null, optional): The expiration time of the certificate used for mTLS connection between the data plane and the control plane.
• list[].status (string, required): - Healthy: Indicates that the gateway instance is functioning normally. This means heartbeat signals are being received regularly, and configuration delivery is working as expected (i.e., configuration revision is in sync).
• OutOfSync: Indicates that the gateway instance is sending heartbeat signals regularly, but the configuration delivery is failing (the configuration revision is out of sync).
• LostConnection: Indicates the gateway instance has lost its heartbeat recently ( 60 seconds < t <= 2 hours )
• Offline: Indicates the gateway instance has lost its heartbeat a long ago ( 2 hours < t < 7 days )

Please note that gateway instances that have been offline for more than 7 days will be removed from the system and will not be included in this API.

• list[].cores (integer, optional): The number of data plane cores.
• list[].compatibility (string, optional): Compatibility between the gateway instance and the control plane, derived from the gateway version and the compatibility report together.
• Compatible: The gateway runs the exact version the control plane expects. The compatibility report is disregarded in this case (there is no other version to move to), so error-level configuration issues only appear in compatibility_report; fix the configuration instead.
• PartiallyCompatible: The gateway version is supported but not the control plane's version, with no error-level configuration issues; an upgrade is recommended.
• Incompatible: The gateway version is unsupported, or it is on a supported-but-different version and reported error-level configuration issues that an upgrade may resolve. An upgrade is required.
• list[].compatibility_report_summary (object, required): Summary of the compatibility report.
• list[].compatibility_report_summary.error_count (integer, required): Number of incompatible resources with error level.
• list[].compatibility_report_summary.warning_count (integer, required): Number of incompatible resources with warning level.
• list[].compatibility_report (array, optional): Per-resource configuration compatibility details reported by the data plane heartbeat (e.g. plugin fields the data plane cannot accept).
• list[].compatibility_report[].type (string, optional): Resource type.
• list[].compatibility_report[].id (string, optional): Resource ID.
• list[].compatibility_report[].error (string, optional): Validation message.
• list[].compatibility_report[].level (string, optional):
• list[].running_mode (string, optional):
• 400: Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.
• value (object, optional): The specific resource.
• error_msg (string, optional): The error message.

cURL

curl -X GET '$API_BASE_URL/api/instances'