Get Security Alerts

Use the IoT Security API to get a list of security alerts.

Synopsis

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

Description

Get a list of security alerts.

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.
type
Optional field specifying the alert type as
policy_alert
. The following value is a string.
resolved
Optional field to get only active alerts (
resolved=no
, the default) or resolved alerts (
resolved=yes
). The following value is a string.
pagelength
Optional but recommended field specifying the number of items for each page. The default page length for alerts is 200 and the maximum is 1000. Setting a shorter length improves response times. The following value is an integer.
offset
In addition to the
pagelength
parameter, use
offset
to get items on subsequent pages. For example, if your first request is
pagelength = 100
, you will get the first 100 device alerts. To get the next 100, add
offset = 100
to your second request. This skips the first 100 alerts and gets the next 100 starting from 101.
sortdirection
Optional field defining whether the alerts are organized in ascending order
asc
(oldest to newest) or descending order
desc
(newest to oldest). The default is
desc
. The following value is a string.
sortfield
Optional field that defines how alerts are ordered. Only
date
is supported as the following value and it is a string.
Request Example
curl 'https://acmecorp.iot.paloaltonetworks.com/pub/v4.0/alert/list?customerid=acmecorp&type=policy_alert&resolved=no&pagelength=1 &sortdirection=descending&sortfield=date' -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 an array of JSON objects, representing devices and their attributes.
Field
Description
resolved
Whether the alert has been resolved
yes
or not
no
(string)
date
The alert detection date
deviceid
The MAC address or IP address of a device (string)
name
The alert name (string)
severity
The severity level of an alert: high, medium, low, info (string)
severityNumber
The severity number matching the severity level: high = 4, medium = 3, low = 2, info = 1 (integer)
type
The type of alert (string)
description
The alert description (string)
tenantid
The internal customer ID (string)
zb_ticketid
The unique ticket ID (integer)
id
The alert ID. This is the ID to use when resolving an alert through the API (integer)
profile
The device profile to which the alert belongs (string)
category
The device category to which the alert belongs (string)
hostname
The hostname of the device to which the alert belongs (string)
siteid
The ID number that IoT Security assigns to the site for internal use (string)
serviceLevel
(For MSSP only) The level of service for an MSSP customer as defined by the MSSP owner; for example:
Tier 1, Tier 2, Tier 3
; or
Platinum, Gold, Silver
(string)
trafficDirection
The direction of the traffic on the device that triggered the alert;
inbound
if the device is a server and
outbound
if it is a client (string)
siteName
The name of the site where the alert occurred (string)
reason_history
The history of actions taken to investigate and resolve the alert (string)
Success Response Example
{"ver": "v4.0", "api": "/alert/list", "items": [ { "resolved": "no", "date": "2020-05-12T01:23:10.630Z", "deviceid": "18:65:90:cd:88:0d", "name": "zingcloud alert bg job integration test at 1589246590630", "severity": "high", "severityNumber": 4, "type": "policy_alert", "description": "The baseline policy defines a criteria to match normal connections between devices in two different networks or device groups. It is a positive detection if connections outside of this definition are observed.", "tenantid": "acmecorp" "zb_ticketid": "alert-hNMleG1nW", "id": "5eb9fa8127b736d82bf7840a", "profile": "Macintosh-MacPro", "category": "Personal Computer", "hostname": "cntl-201-2", "siteid": "0", "serviceLevel": "", "trafficDirection": "inbound", "siteName": "acmecorp-hq", "reason_history": [] "msg": { "severity": "high", "description": "The baseline policy defines criteria to match normal connections between devices in two different networks or device groups. It is a positive detection if connections outside of this definition are observed.", "name": "zingcloud alert bg job integration test at 1589246590630", "id": "hNMleG1nW", "ruleid": "5a26f169c8272f0b00c5ef1a", "zb_ticketid": "alert-hNMleG1nW", "hostname": "unknown", ... } }, . . . ], "total": 3975 }

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. Got an invalid JSON.
401
Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.
402
Unauthorized access. User does not have the required license type to run this API.
403
Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.
500
Internal server error. A unified status for API communication type errors.
Error Response Format
{code: STATUS_CODE, msg: GENERAL_MESSAGE}

Recommended For You