SitesDevices

searchSiteDevices

GET
/api/v1/sites/{site_id}/devices/search

Search devices in a site with filters for device type, identifiers, model, software version, radio settings, LLDP details, and other inventory attributes. Use Search Org Devices to search devices across the organization.

Authorization

Authorization<token>

Preferred authentication method for automation and integrations. Send the API token in the HTTP Authorization header.

Format: Authorization: Token {apitoken}

Notes:

  • An API token generated for a specific admin has the same privileges as that admin
  • An API token is automatically removed if it is not used for more than 90 days
  • SSO admins cannot generate admin API tokens. Use organization API tokens when scoped Org/Site privileges are needed.

In: header

Path Parameters

site_id*string
Formatuuid

Query Parameters

band_24_channel?integer

When type==ap, Channel of band_24

band_5_channel?integer

When type==ap, Channel of band_5

band_6_channel?integer

When type==ap, Channel of band_6

band_24_bandwidth?integer

When type==ap, Bandwidth of band_24

band_5_bandwidth?integer

When type==ap, Bandwidth of band_5

band_6_bandwidth?integer

When type==ap, Bandwidth of band_6

band_24_power?integer

When type==ap, Power of band_24

band_5_power?integer

When type==ap, Power of band_5

band_6_power?integer

When type==ap, Power of band_6

clustered?boolean

When type==gateway, true / false

eth0_port_speed?integer

When type==ap, Port speed of eth0

evpntopo_id?string

When type==switch, EVPN topology id

Formatuuid
ext_ip?string

Partial / full Device external ip. Use prefix* for prefix search or *substring* for contains search (e.g. 1.2.3.* and *.2.3.* match 1.2.3.4). Suffix-only wildcards (e.g. *.2.3.4) are not supported

hostname?string

Partial / full Device hostname. Use prefix* for prefix search or *substring* for contains search (e.g. my-london* and *london* match my-london-1). Suffix-only wildcards (e.g. *london-1) are not supported

ip?string

Partial / full Device IP address. Use prefix* for prefix search or *substring* for contains search (e.g. 10.100.10.* and *100.10.* match 10.100.10.54). Suffix-only wildcards (e.g. *.54) are not supported

last_config_status?string

When type==switch or type==gateway, last configuration status

last_hostname?string

Last hostname of the device.

lldp_mgmt_addr?string

When type==ap, LLDP management IP address

lldp_port_id?string

When type==ap, LLDP port id. Use prefix* for prefix search or *substring* for contains search (e.g. ge-0/0/* and *-0/0/* match ge-0/0/30). Suffix-only wildcards (e.g. *switch-01) are not supported

lldp_system_desc?string

When type==ap, LLDP system description. Use prefix* for prefix search or *substring* for contains search (e.g. Juniper Networks* and *Networks* match Juniper Networks, Inc.). Suffix-only wildcards (e.g. *switch-01) are not supported

lldp_system_name?string

When type==ap, LLDP system name. Use prefix* for prefix search or *substring* for contains search (e.g. my-switch* and *switch* match my-switch-01). Suffix-only wildcards (e.g. *switch-01) are not supported

mac?string

Partial / full Device MAC address. Use prefix* for prefix search or *substring* for contains search (e.g. 001122* and *1122* match 001122334455). Suffix-only wildcards (e.g. *4455) are not supported

model?string

Partial / full Device model. Use prefix* for prefix search or *substring* for contains search (e.g. AP4* and *P4* match AP43). Suffix-only wildcards (e.g. *43) are not supported

mxedge_id?string

When type==ap, Mist Edge id, if AP is connecting to a Mist Edge

Formatuuid
mxedge_ids?string

When type==ap, Comma separated list of Mist Edge id, if AP is connecting to a Mist Edge

mxtunnel_status?string

When type==ap, Mist Tunnel status used to filter results. enum: down, up

Value in

  • "down"
  • "up"
node?string

When type==gateway. enum: node0, node1

Value in

  • "node0"
  • "node1"
node0_mac?string

When type==gateway, node0 MAC address

node1_mac?string

When type==gateway, node1 MAC address

power_constrained?boolean

When type==ap, whether the AP is power constrained

radius_stats?string

When type==switch or type==gateway, Key-value pairs where the key is the RADIUS server address and the value contains authentication statistics:

  • <server_address> (string): IP address of the RADIUS server as the key
  • auth_accepts (long): Number of accepted authentication requests
  • auth_rejects (long): Number of rejected authentication requests
  • auth_timeouts (long): Number of authentication timeouts
  • auth_server_status (string): Status of the server. Possible values: up, down, unreachable
stats?boolean

Whether to return device stats

Defaultfalse
t128agent_version?string

When type==gateway (SSR only), version of 128T agent

type?string

Device type used to filter results. enum: ap, gateway, switch

Default"ap"

Value in

  • "ap"
  • "gateway"
  • "switch"
version?string

Filter results by software version

limit?integer

Maximum number of results to return per page

Range0 <= value
Default100
start?string

Lower bound of the time range, as an epoch timestamp in seconds or a relative value such as -1d or -1w

end?string

Upper bound of the time range, as an epoch timestamp in seconds or a relative value such as -1d, -2h, or now

duration?string

Time range duration for the query, using relative units such as 10m, 7d, or 2w

Default"1d"
sort?string

Field used to sort results; a leading - indicates descending order. enum: mac, model, sku, timestamp

Default"timestamp"

Value in

  • "mac"
  • "model"
  • "sku"
  • "timestamp"
desc_sort?string

Field used to sort results in descending order. enum: mac, model, sku, timestamp

Value in

  • "mac"
  • "model"
  • "sku"
  • "timestamp"
search_after?string

Pagination cursor for retrieving subsequent pages of results. This value is automatically populated by Mist in the next URL from the previous response and should not be manually constructed.

Response Body

curl -X GET "https://example.com/api/v1/sites/000000ab-00ab-00ab-00ab-0000000000ab/devices/search"

{  "end": 0,  "limit": 0,  "next": "string",  "results": [    {      "hostname": [        "AP41-STB-3E5299-WH-2001",        "AP41-STB-3E5299-WH-50",        "AP41-STB-3E5299",        "5c5b353e5299"      ],      "ip": "10.2.16.205",      "lldp_mgmt_addr": "10.2.10.139",      "lldp_port_desc": "GigabitEthernet1/0/1",      "lldp_port_id": "Gi1/0/1",      "lldp_system_desc": "Cisco IOS Software, C2960S Software (C2960S-UNIVERSALK9-M), Version 15.2(1)E1, RELEASE SOFTWARE (fc2)\nTechnical Support: https://www.cisco.com/techsupport\nCopyright (c) 1986-2013 by Cisco Systems, Inc.\nCompiled Fri 22-Nov-13 07:10 by prod_rel_team",      "lldp_system_name": "ME-DC-1-ACC-SW",      "mac": "5c5b353e5299",      "model": "AP41",      "mxedge_id": "00000000-0000-0000-1000-43a81f238391",      "mxtunnel_status": "down",      "org_id": "6748cfa6-4e12-11e6-9188-0242ac110007",      "power_constrained": false,      "power_opmode": "",      "site_id": "a8178443-ecb5-461c-b854-f16627619ab3",      "sku": "AP41-US",      "timestamp": 1596588619.007,      "uptime": 85280,      "version": "0.7.20216",      "wlans": [        {          "id": "28c36fc7-dc22-4960-9d81-34087511c2e5",          "ssid": "Live-Demo-NAC"        },        {          "id": "51b82e2b-f9e8-470b-a32a-cecde5501b0f",          "ssid": "Live-Demo"        }      ]    }  ],  "start": 0,  "total": 0}