Select the tab
ESET Connect – Table of Contents

GET List incidents

Relative path: /v3/incidents

Returns a list of incidents matching the filter.
The list is ordered according to order_by.

Info: This API call returns empty values for deviceUuids and detectionUuids to reduce the response size. To retrieve the values, execute the GET /v2/incidents/{incidentUuid} API call for a specific incident.

Endpoint URL for Europe, Germany, United States, Canada and Japan regions:






Filtering

Field names for filtering must be specified using the snake case or the lower camel case, for example, display_name or displayName.

Supported fields for filtering are:

•create_time

•update_time

•display_name

•assignee_uuid

•device_uuids

•severity

•status

•tags

Operators for filtering

•==—Equality operator, for example, incident.display_name == "name"

•!=—Inequality operator, for example, incident.assignee_uuid != "uuid"

•<=—Less than or equal to operator, for example, incident.create_time >= timestamp("2025-10-01T12:30:00+00:00")

•>=—Greater than or equal to operator, for example, size(incident.device_uuids) >= 10 or incident.device_uuids.size() >= 10

•in—Filters items with values specified in the list, for example, incident.severity in [INCIDENT_SEVERITY_LEVEL_LOW,INCIDENT_SEVERITY_LEVEL_MEDIUM]

•contains—Filters items where the value contains the specified text, for example, incident.display_name.contains("xyz")

•has—Filters items that have the specified key, for example, has(incident.assignee_uuid)

•&&—"And" operator, mostly used for time filtering, for example, incident.create_time >= timestamp("2025-04-07T00:00:00Z") && incident.create_time <= timestamp("2025-04-18T23:59:59Z")

Status filtering examples

Filter by status using only the in or == operator.


Severity filtering examples

Filter by severity using only the in or == operator.


Time filtering examples

Filter by create_time or update_time using the timestamp offset or UTC representation as in the examples below.


UUID filtering examples

Filter by uuid using comparison filters.


Display name filtering examples


Ordering

Field names for ordering must be specified using the snake case, for example, display_name.

Supported fields for ordering are:

•display_name

•create_time

•update_time

•severity

•status

•device_uuids.count

•detection_uuids.count

Query parameters

Name

Type

Description

pageSize

integer

Limit for pagination purposes.

If unspecified or 0, the default value is 50. The maximum value is 1000; values above 1000 will be coerced to 1000.

Info: For more information, refer to Paginating Requests in APIs

or Design Patterns: Pagination

pageToken

string

Page token of the current page.

If not given or "", the first page is returned.

Info: For more information, refer to Paginating Requests in APIs

or Design Patterns: Pagination

orderBy

string

Comma-separated list of fields (from the request resource).

For example, a result set will be ordered by display name and severity level in the descending order, what can be encoded as display_name, SeverityLevel desc.

Allowed formats are: - snake_case version of the field name as used by protocol buffers. - JSON version of the field name

The syntax is described at Standard Methods: List Ordering

filter

string

A filter string compliant with Filtering. Field names must be expressed in lower_case_with_underscores form or in lowerCamelCase form, for example, display_name or displayName. For time filtering, use the timestamp offset representation.

Examples: - incident.create_time >= timestamp("2024-10-01T12:41:39+00:00") - incident.displayName.contains("abc") - displayName.contains("abc")

Info: Common Expression Language is defined at GitHub: Google Open Source along with libraries for C++/C#, Go



Responses

Code

Description and Example

Description, Schema and Headers

200

Successful response.


Response example

{
  "incidents": [
    {
      "affectedAssets": [
        {
          "deviceUuid": "string",
          "identityUuid": "string"
        }
      ],
      "assigneeUuid": "string",
      "createTime": "string",
      "description": "string",
      "displayName": "string",
      "indicatorUuids": [
        "string"
      ],
      "mitreTechniqueIds": [
        "string"
      ],
      "resolveReason": "INCIDENT_RESOLVE_REASON_UNSPECIFIED",
      "responseDuration": "string",
      "severity": "INCIDENT_SEVERITY_LEVEL_UNSPECIFIED",
      "status": "INCIDENT_STATUS_UNSPECIFIED",
      "tags": [
        "string"
      ],
      "triageDuration": "string",
      "updateTime": "string",
      "uuid": "string",
      "authorUuid": "string",
      "editorUuid": "string",
      "ownerUuid": "string"
    }
  ],
  "nextPageToken": "string"
}

Successful response.


Response schema

{
  "$ref": "incident_managementv3ListIncidentsResponse",
  "incidents": [
    {
      "$ref": "incident_managementv3Incident",
      "description": {
        "type": "string",
        "description": "Arbitrary text describing the incident."
      },
      "affectedAssets": [
        {
          "$ref": "v3AffectedAsset",
          "deviceUuid": {
            "type": "string",
            "description": "Reference to [device]. type: device_management.v1.Device"
          },
          "identityUuid": {
            "type": "string",
            "description": "Reference to [identity]. type: identity_management.v1.Identity"
          }
        }
      ],
      "assigneeUuid": {
        "type": "string",
        "description": "User responsible for investigation and remediation. type: user_management.v1.User"
      },
      "createTime": {
        "type": "string",
        "description": "Timestamp for when the incident was created.",
        "format": "date-time",
        "readOnly": true
      },
      "displayName": {
        "type": "string",
        "description": "Human readable name of the incident."
      },
      "indicatorUuids": [
        {
          "type": "string"
        }
      ],
      "mitreTechniqueIds": [
        {
          "type": "string"
        }
      ],
      "resolveReason": {
        "$ref": "incident_managementv3IncidentResolveReason",
        "type": "string",
        "description": "Possible reasons for resolved incident. INCIDENT_RESOLVE_REASON_UNSPECIFIED: fallback INCIDENT_RESOLVE_REASON_TRUE_POSITIVE: The incident was a true positive, indicating a genuine security threat. INCIDENT_RESOLVE_REASON_FALSE_POSITIVE: The incident was initially thought to be a security threat but later determined to be a false alarm. INCIDENT_RESOLVE_REASON_SUSPICIOUS: The incident is not a confirmed threat (true positive), but investigating it can provide valuable insights into user behavior patterns and help mitigate potential attacks.",
        "default": "INCIDENT_RESOLVE_REASON_UNSPECIFIED",
        "enum": [
          "INCIDENT_RESOLVE_REASON_UNSPECIFIED",
          "INCIDENT_RESOLVE_REASON_TRUE_POSITIVE",
          "INCIDENT_RESOLVE_REASON_FALSE_POSITIVE",
          "INCIDENT_RESOLVE_REASON_SUSPICIOUS"
        ]
      },
      "responseDuration": {
        "type": "string",
        "description": "How long did it take to respond to the incident.",
        "readOnly": true
      },
      "severity": {
        "$ref": "incident_managementv3IncidentSeverityLevel",
        "type": "string",
        "description": "Severity levels abstracted to cover all the possible GUIs. Vocabulary is leaving interpretation of severity level completely to API client. Info: This approach is inevitable on SIEM level as there are many contributing sources. Keeping the local names for severity levels never fits all the GUIs. INCIDENT_SEVERITY_LEVEL_UNSPECIFIED: fallback INCIDENT_SEVERITY_LEVEL_LOW: In some GUIs known Warning INCIDENT_SEVERITY_LEVEL_MEDIUM: In some GUIs known as Error or Threat INCIDENT_SEVERITY_LEVEL_HIGH: In some GUIs known as Critical",
        "default": "INCIDENT_SEVERITY_LEVEL_UNSPECIFIED",
        "enum": [
          "INCIDENT_SEVERITY_LEVEL_UNSPECIFIED",
          "INCIDENT_SEVERITY_LEVEL_LOW",
          "INCIDENT_SEVERITY_LEVEL_MEDIUM",
          "INCIDENT_SEVERITY_LEVEL_HIGH"
        ]
      },
      "status": {
        "$ref": "incident_managementv3IncidentStatus",
        "type": "string",
        "description": "Define an enumeration for incident status. INCIDENT_STATUS_UNSPECIFIED: fallback INCIDENT_STATUS_OPEN: The incident is OPEN (aka NEW) and has been reported or detected. INCIDENT_STATUS_IN_PROGRESS: The incident is currently in progress and being actively addressed. INCIDENT_STATUS_CLOSED: The incident has been closed, and the necessary actions have been taken. INCIDENT_STATUS_WAITING_FOR_INPUT: The incident is awaiting input from the customer.",
        "default": "INCIDENT_STATUS_UNSPECIFIED",
        "enum": [
          "INCIDENT_STATUS_UNSPECIFIED",
          "INCIDENT_STATUS_OPEN",
          "INCIDENT_STATUS_IN_PROGRESS",
          "INCIDENT_STATUS_CLOSED",
          "INCIDENT_STATUS_WAITING_FOR_INPUT"
        ]
      },
      "tags": [
        {
          "type": "string"
        }
      ],
      "triageDuration": {
        "type": "string",
        "description": "How long incident remained in triage status.",
        "readOnly": true
      },
      "updateTime": {
        "type": "string",
        "description": "Represents the timestamp when the resource was most recently updated. Any change to the resource made by users (create/update/delete) must update this value; changes to a resource made internally by the service should refresh this value unless specified otherwise on entity level. info: Modeled after: https://google.aip.dev/148#timestamps",
        "format": "date-time",
        "readOnly": true
      },
      "uuid": {
        "type": "string",
        "description": "Unique identifier of the entity. Must be collision-free - two identifiers created anywhere in the world must not collide within the entity parent scope. Unless a member of aggregate, the entity scope is always global. Although most of the times compliant with RFC 9562: A Universally Unique IDentifier (UUID) URN Namespace, do not rely on it being a RFC UUID. Treat it as an opaque identifier, albeit of predictable length and alphabet. RFC UUID can be recognized by being formatted according to the template xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx, as explained on Wikipedia. UUID is used for referencing an entity, even across domains. Example: '123e4567-e89b-12d3-a456-426614174000'"
      },
      "authorUuid": {
        "type": "string",
        "description": "Principal responsible for the first revision of the entity. It might be the identification of the user. type: user_management.v1.User",
        "readOnly": true
      },
      "editorUuid": {
        "type": "string",
        "description": "Principal responsible for the revision of the entity. It might be the identification of the user. Every revision might have a different editor. For non-revisioned entities, the editor denotes the author of the last revision. For just-created entities, author and editor are the same. type: user_management.v1.User",
        "readOnly": true
      },
      "ownerUuid": {
        "type": "string",
        "description": "Identifier of the tenant who owns this object. type: tenant_management.v1.Tenant",
        "readOnly": true
      }
    }
  ],
  "nextPageToken": {
    "type": "string",
    "description": "Page token of the next page. Empty or '' for the last page. Info: For more information, refer to Paginating Requests in APIs or Design Patterns: Pagination"
  }
}


Headers

{
  "request-id": {
    "description": "Unique ID of the request. Include in support requests.",
    "style": "simple",
    "explode": false,
    "schema": {
      "type": "string",
      "format": "uuid"
    }
  }
}

202

Response took too long; request cached. Response can be retrieved later using the response-id header.

Response took too long; request cached. Response can be retrieved later using the response-id header.


Response schema

[]


Headers

{
  "response-id": {
    "description": "Unique ID of a pending request. Used to retrieve cached result.",
    "style": "simple",
    "explode": false,
    "schema": {
      "type": "string",
      "format": "uuid"
    }
  },
  "request-id": {
    "description": "Unique ID of the request. Include in support requests.",
    "style": "simple",
    "explode": false,
    "schema": {
      "type": "string",
      "format": "uuid"
    }
  }
}

400

One of the errors: 1. Bad or missing authorization. 2. Validation error. Invalid argument provided.

One of the errors: 1. Bad or missing authorization. 2. Validation error. Invalid argument provided.


Response schema

[]


Headers

{
  "request-id": {
    "description": "Unique ID of the request. Include in support requests.",
    "style": "simple",
    "explode": false,
    "schema": {
      "type": "string",
      "format": "uuid"
    }
  }
}

401

Token has expired or is invalid.

Token has expired or is invalid.


Response schema

[]


Headers

{
  "request-id": {
    "description": "Unique ID of the request. Include in support requests.",
    "style": "simple",
    "explode": false,
    "schema": {
      "type": "string",
      "format": "uuid"
    }
  }
}

403

Access denied. Check permissions.

Access denied. Check permissions.


Response schema

[]


Headers

{
  "request-id": {
    "description": "Unique ID of the request. Include in support requests.",
    "style": "simple",
    "explode": false,
    "schema": {
      "type": "string",
      "format": "uuid"
    }
  }
}

404

Requested resource not found.

Requested resource not found.


Response schema

[]


Headers

{
  "request-id": {
    "description": "Unique ID of the request. Include in support requests.",
    "style": "simple",
    "explode": false,
    "schema": {
      "type": "string",
      "format": "uuid"
    }
  }
}

429

Rate limit reached. Try again later.

Rate limit reached. Try again later.


Response schema

[]


Headers

{
  "request-id": {
    "description": "Unique ID of the request. Include in support requests.",
    "style": "simple",
    "explode": false,
    "schema": {
      "type": "string",
      "format": "uuid"
    }
  }
}

500

Internal server failure. Try again later.

Internal server failure. Try again later.


Response schema

[]


Headers

{
  "request-id": {
    "description": "Unique ID of the request. Include in support requests.",
    "style": "simple",
    "explode": false,
    "schema": {
      "type": "string",
      "format": "uuid"
    }
  }
}

502

Internal server failure. Try again later.

Internal server failure. Try again later.


Response schema

[]


Headers

{
  "request-id": {
    "description": "Unique ID of the request. Include in support requests.",
    "style": "simple",
    "explode": false,
    "schema": {
      "type": "string",
      "format": "uuid"
    }
  }
}

503

Environment under maintenance. Try again later.

Environment under maintenance. Try again later.


Response schema

[]


Headers

{
  "request-id": {
    "description": "Unique ID of the request. Include in support requests.",
    "style": "simple",
    "explode": false,
    "schema": {
      "type": "string",
      "format": "uuid"
    }
  }
}

504

Action took too long; timeout reached

Action took too long; timeout reached


Response schema

[]


Headers

{
  "request-id": {
    "description": "Unique ID of the request. Include in support requests.",
    "style": "simple",
    "explode": false,
    "schema": {
      "type": "string",
      "format": "uuid"
    }
  }
}