List Data Plane Nodes

GET /environments/{env_id}/dp_nodes

List Data Plane Nodes

List the data plane nodes that have connected to the environment. A node appears after its first status report; a gateway certificate that was issued but never used to connect is not listed. Each entry reflects the node's most recent report, including which configuration revision it has applied and the delivery health of its observability exporters.

Nodes that have stopped reporting stay listed for about an hour with status offline — a restart or a rolling upgrade therefore leaves entries for the processes it replaced. Filter or group by status to count the nodes that are currently reporting.

Parameters

• env_id (path, string, required): Environment ID that scopes the request.

Responses

• 200: OK

• data (array, required): Data plane nodes that have connected to the environment, grouped by gateway certificate, newest certificate first.

• data[].id (string, required): Per-process node identifier, unique to one node start.

• data[].dp_id (string, required): ID of the gateway certificate the node authenticated with. Replicas deployed from the same certificate bundle share this value.

• data[].env_id (string, required): Environment ID the node serves.

• data[].hostname (string, required): Hostname the node reported. Falls back to the label chosen when the node's gateway certificate was issued if the node does not report one.

• data[].dp_version (string, required): Gateway software version the node reported. Empty for gateway versions that do not report one.

• data[].dp_protocol_version (string, required): Version of the AISIX Cloud connection protocol recorded when the node's gateway certificate was issued.

• data[].registered_at (string, required): Time when the node first connected.

• data[].last_heartbeat_at (string, required): Time of the node's most recent status report.

• data[].status (string, required): Whether the node is still reporting, decided by AISIX Cloud from the time of its most recent status report. healthy: reported within the last two report intervals. warning: silent for more than two intervals but fewer than five — it has missed reports but is not yet presumed gone. offline: silent for five intervals or more.

This describes reporting only. It is not a judgement about the traffic the node is serving, and it is independent of partially_compatible_resources, which describes configuration compatibility.

The interval is the node's configured heartbeat interval (15 seconds by default), so the default thresholds are 30 and 75 seconds. A node deliberately configured to report less often than the default reaches warning or offline between its own reports.

Restarting a node leaves its previous entry in the list with the report time it stopped at; that entry moves to offline and is removed about an hour later. Use this field rather than comparing last_heartbeat_at against your own clock.

• data[].supported_guardrail_kinds (array, optional): Guardrail kinds this node's gateway build can enforce. Omitted for gateway versions that do not report capabilities.

• data[].applied_revision (integer, optional): The newest configuration revision the node has applied. Compare with the list-level store_revision to see whether the node has caught up with the latest saved configuration. Omitted when the node has not reported a nonzero revision — an older gateway version, or a node that has not yet applied any configuration.

• data[].config_hash (string, optional): SHA-256 fingerprint of the configuration snapshot the node currently has applied, as reported by the node. Two nodes reporting the same value are running identical configuration. For nodes receiving configuration from AISIX Cloud, the hash is computed over all configuration entries in ascending key order, each rendered as the entry key, a NUL byte, the entry's canonical JSON (object keys sorted recursively, no whitespace), and a newline. For nodes running from a local configuration file, it is the SHA-256 of the raw file bytes. Omitted for gateway versions that do not report it.

• data[].exporter_health (array, optional): Delivery health of each observability exporter configured on the node, as reported by the node. Omitted for gateway versions that do not report it and for nodes with no exporters.

• data[].exporter_health[].name (string, optional): Name of the exporter the counters belong to.

• data[].exporter_health[].delivered_batches (integer, optional): Telemetry batches delivered successfully.

• data[].exporter_health[].failed_batches (integer, optional): Telemetry batches that failed to deliver.

• data[].exporter_health[].last_error (string, optional): Most recent delivery error, truncated by the gateway. null once a later delivery succeeds.

• data[].exporter_health[].last_failure_unix (integer, optional): Unix timestamp (seconds) of the most recent failed delivery, or null if none has failed.

• data[].exporter_health[].last_success_unix (integer, optional): Unix timestamp (seconds) of the most recent successful delivery, or null if none has succeeded.

• data[].partially_compatible_resources (array, optional): Configuration entries this node serves while ignoring fields its gateway build does not recognize, grouped by resource kind and field path. Entries appear here when configuration written by a newer AISIX Cloud release reaches a node running an older gateway build — typically during a rolling gateway upgrade — and disappear once the node is upgraded. Omitted when the node reports none. Gateway versions below 0.8.0 cannot report this, so an omitted value is not by itself a confirmation of full compatibility.

• data[].partially_compatible_resources[].kind (string, required): Resource collection of the affected entries — for example api_keys or models.

• data[].partially_compatible_resources[].field (string, required): Dot-separated path of the ignored field, with array positions rendered as [] — for example routing.targets[].priority. A node reports at most 64 distinct paths for one configuration entry; when an entry exceeds that, the literal value ...truncated appears as an additional path.

• data[].partially_compatible_resources[].count (integer, required): Number of configuration entries of this kind carrying the ignored field. A node tracks at most 1024 entries across all kinds, so once that retention is full every count is a lower bound rather than an exact total.

• store_revision (integer, optional): The newest configuration revision AISIX Cloud has published for delivery to the environment's nodes. A node whose applied_revision has reached this value is running the latest saved configuration. 0 until the first delivery. Omitted when revision tracking is unavailable on the deployment or the revision could not be read for this response.

• 400: Request body or parameters failed validation.

• error (object, required): Error details.

• error.code (string, required): Machine-readable identifier. Examples: UNAUTHENTICATED, INVALID_REQUEST, MASTER_KEY_UNSET, INTERNAL.

• error.message (string, required): Human-readable explanation; safe to surface to operators.

• 401: Missing or invalid bearer. Response fields (application/json): identical to GET /environments/{env_id}/dp_nodes, response 400 above.

• 404: Resource not found. Response fields (application/json): identical to GET /environments/{env_id}/dp_nodes, response 400 above.

• 503: The deployment is not configured to serve this data. Response fields (application/json): identical to GET /environments/{env_id}/dp_nodes, response 400 above.

cURL

curl -X GET '$AISIX_CP/environments/{env_id}/dp_nodes' -H 'Authorization: Bearer $AISIX_TOKEN'