Get the Device Inventory

Use the IoT Security API to get a list of all the devices in your inventory.

Synopsis

URI
/pub/v4.0/device/list
HTTP Method
GET
FQDN
<customer-name>.iot.paloaltonetworks.com

Description

Get a list of all the devices in your IoT Security inventory.

Request Fields

The URL of this request contains the following parameters:
Field
Description
customerid
(
Required
) The customer ID specifies the API call for a specific tenant.
The following value is a string.
For other parameters you can include in the URL—such as
offset
,
pagelength
,
sortdirection
,
sortfield
and
stime
—see the general parameters and device-specific parameters described in Get Started with the IoT Security API.
Request Example
curl --location -X GET 'https://acmecorp.iot.paloaltonetworks.com/pub/v4.0/device/list?customerid=acmecorp' \ -H 'X-Key-Id: KEY_ID' \ -H 'X-Access-Key: ACCESS_KEY'

Success Response

Upon success, the HTTP response code is 200. In addition, this API returns a JSON object containing devices and their attributes.
Field
Description
total
The number of devices matching the request
devices
An array containing device details
deviceid
The device ID, which IoT Security uses to identify and track a device (string)
hostname
Device hostname (string)
category
Category to which a device belongs (string)
profile
Device profile assigned to a device (string)
profile_type
Type of device profile, such as
IoT
or
Non_IoT
(string)
profile_vertical
Industry vertical for a device profile such as
Medical
,
IT Devices
, and
Office
(string)
ip_address
IP address of a device (string)
mac_address
MAC address of a device (string)
risk_score
Risk score of a device (integer)
risk_level
Risk level of a device; there are four:
low
,
medium
,
high
, and
critical
(string)
last_activity
UTC timestamp for the last detected device activity (object)
confidence_score
Confidence score for device classification (integer)
trafficRestricted
Whether traffic restriction is being applied to a device (
yes
) or not (
no
)
tagIdList
A list of IDs for user- and system-defined tags assigned to a device
allTags
An array of user-defined tags assigned to a device. Each item in the array consists of three attributes:
tagType
,
tagValue
, and
tagId
.
tagType
The key for a user-defined tag
tagValue
The value of the key for a user-defined tag
tagId
The ID of a user-defined tag
total
The total number of devices for which information was returned
To get more attributes for each device, include
detail=true
in the request. See Device-specific parameters in Get Started with the IoT Security API.
Success Response Example
{ "devices": [ { "deviceid": "34:02:86:44:65:36", "hostname": "InfusionPump-20", "last_activity": "2018-05-31T18:39:37.404Z", "category": "Infusion System", "profile": "Sigma Spectrum Infusion System", "profile_type": "IoT", "profile_vertical": "Medical", "ip_address": "192.168.10.121", "mac_address": "34:02:86:44:65:36", "risk_score": 0, "risk_level": "low", "confidence_score": 90}, "trafficRestricted": "no", "tagIdList": [ "60f221a219e22f10003a965e" ], "allTags": [ { "tagType": "med-equipment", "tagValue": "infusion", "tagId": "60f221a219e22f10003a965e" } ] } ... ], "total": 100 }
Data is shown for only the first of 100 devices in the full response, and detail mode is off.

Error Response

Upon error, the reply includes an HTTP response code, an error message, and additional information describing the error. The HTTP response code is one of the following:
Field
Description
400
Bad Request. This occurs when an HTTP request contains an invalid query string.
403
Forbidden access. Either the provided API Key is invalid or it does not have the required RBAC permissions to run this API.
429
Too many requests. The number of requests for the device inventory list exceeded the rate limit of 60 queries per minute per tenant.
500
Internal server error. A unified status for API communication type errors.
Error Response Format
{code: STATUS_CODE, msg: GENERAL_MESSAGE}

Recommended For You