GET /bgp/peers

List BGP peers discovered via BMP or SNMP BGP4-MIB walks, with optional filtering and pagination. Each peer carries source ("bmp" — BMP Peer Up/Down evidence, the richer view — or "snmp" — a bgpPeerTable walk on a router without BMP export; IPv4-ADDRESSED sessions only, and a 4-byte remote ASN appears as AS_TRANS 23456 per the MIB's 2-byte fields). prefixes_received is absent when not measured — the plain BGP4-MIB has no prefix counter; on Cisco agents the walk also reads cbgpPeerAcceptedPrefixes (CISCO-BGP4-MIB, per AFI/SAFI), which fills real counts AND surfaces the further address families a session carries as their own peer rows (an IPv6-unicast AF over an IPv4 session appears as an address_family: "ipv6" row with the session's IPv4 peer_ip). Non-Cisco agents keep the documented v4-only view with no counts.

Auth: all authenticated roles

Query params:

Param Type Description
device_id UUID Filter by device
as_id UUID Filter by autonomous system
target_id UUID Filter by BMP target
state string Filter by peer state (up, down)
peer_type string Filter by peer type (ibgp, ebgp)
af string Filter by address family (ipv4, ipv6, vpnv4, vpnv6)
limit int Max results (default 50, max 1000)
offset int Pagination offset (default 0)
at RFC 3339 As-of-T: return peer sessions from bgp_peer_history at this time instead of the live state. Malformed → 400.

Response: 200 OK

{
  "peers": [
    {
      "id": "uuid",
      "device_id": "uuid",
      "as_id": "uuid",
      "peer_ip": "198.51.100.2",
      "peer_as": 65002,
      "local_ip": "198.51.100.1",
      "local_as": 65001,
      "peer_type": "ebgp",
      "address_family": "ipv4",
      "state": "up",
      "prefixes_received": 150000,
      "peer_router_id": "198.51.100.2",
      "peer_bgp_id": "198.51.100.2",
      "add_paths_negotiated": false,
      "send_community": true,
      "bmp_target_id": "uuid",
      "hold_time": 90,
      "keepalive_interval": 30,
      "last_notification_code": null,
      "last_notification_subcode": null,
      "source": "bmp",
      "first_seen": "2026-03-01T00:00:00Z",
      "last_seen": "2026-03-18T12:00:00Z",
      "created_at": "2026-03-01T00:00:00Z",
      "updated_at": "2026-03-18T12:00:00Z",
      "device_hostname": "rr1",
      "peer_hostname": "peer2.example.com"
    }
  ],
  "total": 42,
  "up": 38,
  "unique_peers": 7,
  "limit": 50,
  "offset": 0
}

created_at/updated_at are always present. peer_bgp_id (the peer's BGP Identifier), peer_hostname (joined display name for the peer), and the timer / notification fields are omitempty — present only when populated.

total counts sessions — one row per reporting device × peer × address family, so a peer reported by six BMP-exporting routers contributes six rows (device_hostname identifies the reporter). up counts sessions in state up and unique_peers counts distinct (peer IP, AF) combinations; both are computed over the whole filtered set, not the returned page.

When at is supplied, the counts and rows come from the session history as-of-T; a notice string is added (and total is 0) when the window has no recorded sessions — BGP history may not cover the selected time.