Skip to main content

Get Security Alerts

Get a list of security alerts.
Rate limiting: 60 times per minute

Query Parameters
  • customerid string required

    The customer ID to which the API call is directed

  • type string

    A field that specifies the alert type as policy_alert

  • resolved string

    A filter to retrieve only active alerts (resolved=no, the default) or resolved alerts (resolved=yes)

  • offset integer

    In addition to the pagelength parameter, offset gets items on subsequent pages. For example, if the page length of your first request is 100, you get the first 100 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.

  • pagelength integer

    The number of items in one response; that is, in one page. The default page length for alerts is 1000 and the maximum is 1000. Setting a shorter length improves response times.

  • stime string

    The start of a time range for alerts to retrieve. For example, stime=2021-10-6T07:00Z. (It’s unnecessary to set etime=now or etime=<time> because it is always treated as now.)

  • sortdirection string

    The direction in which returned alerts are organized: ascending order asc (oldest to newest) or descending order desc (newest to oldest, the default)

  • sortfield string

    The device attribute to use for sorting. date and severityNumber are supported as the following value and the value types are string and integer respectively. The default way to sort alerts is by date in descending order.

  • updatedCreatedAfter date-time

    Optional field setting the start of a time range for retrieving alerts that have been created in DB or updated.


Successful Response (We only show some important fields here.)

  • total integer

    The number of security alerts matching the request

  • items object[]

    An array containing security alerts

  • Array [
  • resolved string

    Whether the alert has been resolved (yes) or not (no)

  • siteid string

    The ID number that IoT Security assigns to the site for internal use

  • trafficDirection string

    The direction of the traffic on the device that triggered the alert; “inbound” if the device is a server and “outbound” if it’s a client

  • siteName string

    The name of the site where the alert occurred

  • date string

    The alert detection date

  • deviceid string

    The MAC address or IP address of a device

  • name string

    The alert name

  • severity string

    The severity level of an alert: high, medium, low, info

  • severityNumber integer

    The severity number matching the severity level: high = 4, medium = 3, low = 2, info = 1

  • type string

    The type of alert

  • description string

    The alert description

  • tenantid string

    The internal customer ID

  • zb_ticketid string

    The unique ticket ID

  • id string

    The alert ID. This is the ID to use when resolving an alert through the API.

  • profile string

    The device profile to which the alert belongs

  • profile_vertical string

    The industry vertical for the profile such as Medical, IT Devices, and Office

  • category string

    The device category to which the alert belongs

  • hostname string

    The hostname of the device to which the alert belongs

  • reason_history string

    The history of actions taken to investigate and resolve the alert

  • serviceLevel string

    (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.

  • ]
  • deviceTags object

    A list of device tags

  • id object

    The ID numbers of user-defined tags

  • deviceid string

    deviceid is the Key for the DeviceTagMapping

  • tagIdList array

    List of Tag IDs

  • allTags object[]

    List of Tagtype-TagValue pairs for the Device

  • Array [
  • tagType string

    The key for a user-defined tag

  • tagValue string

    The value of the tag key for a user-defined tag

  • tagId string

    The ID of a user-defined tag

  • ]