Skip to main content

Get Security Alerts



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


Query Parameters

    customerid stringrequired

    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

  • ]