GET
/api/peers/{peerId}Retrieve a peer
Retrieves information about a specific peer. Use the peer identifier to look up its identity, connection state, location, and configuration details.
peerIdstringrequired
The unique identifier of the peer to retrieve.
200Returns a peer object with its identifier, name, connection and location details, and configuration fields.
idstringrequired
Peer ID
namestringrequired
Peer's hostname
approval_requiredbooleanrequired
(Cloud only) Indicates whether peer needs approval
city_namestringrequired
Commonly used English name of the city
connectedbooleanrequired
Peer to Management connection status
connection_ipstringrequired
Peer's public connection IP address
country_codestringrequired
2-letter ISO 3166-1 alpha-2 code that represents the country
created_atstringrequired
Peer creation date (UTC)
disapproval_reasonstringoptional
(Cloud only) Reason why the peer requires approval
dns_labelstringrequired
Peer's DNS label is the parsed peer name for domain resolution. It is used to form an FQDN by appending the account's domain to the peer label. e.g. peer-dns-label.netbird.cloud
ephemeralbooleanrequired
Indicates whether the peer is ephemeral or not
extra_dns_labelsarray<string>required
Extra DNS labels added to the peer
geoname_idintegerrequired
Unique identifier from the GeoNames database for a specific geographical location.
groupsarray<object>required
Groups that the peer belongs to
hostnamestringrequired
Hostname of the machine
inactivity_expiration_enabledbooleanrequired
Indicates whether peer inactivity expiration has been enabled or not
ipstringrequired
Peer's IP address
ipv6stringoptional
Peer's IPv6 overlay address
kernel_versionstringrequired
Peer's operating system kernel version
last_loginstringrequired
Last time this peer performed log in (authentication). E.g., user authenticated.
last_seenstringrequired
Last time peer connected to Netbird's management service
local_flagsobjectoptional
login_expiration_enabledbooleanrequired
Indicates whether peer login expiration has been enabled or not
login_expiredbooleanrequired
Indicates whether peer's login expired or not
network_addressesarray<object>optional
Network interfaces (IP + MAC) reported by the peer
osstringrequired
Peer's operating system and version
serial_numberstringrequired
System serial number
ssh_enabledbooleanrequired
Indicates whether SSH server is enabled on this peer
ui_versionstringrequired
Peer's desktop UI version
user_idstringrequired
User ID of the user that enrolled this peer
versionstringrequired
Peer's daemon or cli version
400Returned when the request is invalid.
401Returned when the request lacks required authentication.
403Returned when the request is forbidden.
500Returned when an internal server error occurs.
Error handling
A 400 indicates an invalid request, a 401 indicates missing authentication, a 403 indicates insufficient permission, and a 500 indicates an internal server error. The peerId path parameter must identify the peer you want to retrieve.