Get exception list items

GET /api/exception_lists/items/_find

Get a list of all exception list items in the specified list.

Query parameters

  • list_id array[string(nonempty)] Required

    The list_ids of the items to fetch.

    Minimum length of each is 1.

  • filter array[string(nonempty)]

    Filters the returned results according to the value of the specified field, using the <field name>:<field value> syntax.

    Minimum length of each is 1. Default value is [] (empty).

  • namespace_type array[string]

    Determines whether the returned containers are Kibana associated with a Kibana space or available in all spaces (agnostic or single)

    Values are agnostic or single. Default value is ["single"].

  • page integer

    The page number to return

    Minimum value is 0.

  • per_page integer

    The number of exception list items to return per page

    Minimum value is 0.

  • sort_field string(nonempty)

    Determines which field is used to sort the results.

    Minimum length is 1.

  • Determines the sort order, which can be desc or asc.

    Values are desc or asc.

Responses

  • 200 application/json

    Successful response

    Hide response attributes Show response attributes object
    • data array[object] Required
      Hide data attributes Show data attributes object
      • _version string

        The version id, normally returned by the API when the item was retrieved. Use it ensure updates are done against the latest version.

      • comments array[object] Required

        Array of comment fields:

        • comment (string): Comments about the exception item.
        Hide comments attributes Show comments attributes object
        • comment string(nonempty) Required

          A string that does not contain only whitespace characters

          Minimum length is 1.

        • created_at string(date-time) Required

          Autogenerated date of object creation.

        • created_by string(nonempty) Required

          A string that does not contain only whitespace characters

          Minimum length is 1.

        • id string(nonempty) Required

          A string that does not contain only whitespace characters

          Minimum length is 1.

        • updated_at string(date-time)

          Autogenerated date of last object update.

        • updated_by string(nonempty)

          A string that does not contain only whitespace characters

          Minimum length is 1.

      • created_at string(date-time) Required

        Autogenerated date of object creation.

      • created_by string Required

        Autogenerated value - user that created object.

      • description string Required

        Describes the exception list.

      • entries array[object] Required
        Any of:
        Hide attributes Show attributes
        • field string(nonempty) Required

          A string that does not contain only whitespace characters

          Minimum length is 1.

        • operator string Required

          Values are excluded or included.

        • type string Required Discriminator

          Value is match.

        • value string(nonempty) Required

          A string that does not contain only whitespace characters

          Minimum length is 1.

      • expire_time string(date-time)

        The exception item’s expiration date, in ISO format. This field is only available for regular exception items, not endpoint exceptions.

      • id string(nonempty) Required

        Exception's identifier.

        Minimum length is 1.

      • item_id string(nonempty) Required

        Human readable string identifier, e.g. trusted-linux-processes

        Minimum length is 1.

      • list_id string(nonempty) Required

        Exception list's human readable string identifier, e.g. trusted-linux-processes.

        Minimum length is 1.

      • meta object

        Additional properties are allowed.

      • name string(nonempty) Required

        Exception list name.

        Minimum length is 1.

      • namespace_type string Required

        Determines whether the exception container is available in all Kibana spaces or just the space in which it is created, where:

        • single: Only available in the Kibana space in which it is created.
        • agnostic: Available in all Kibana spaces.

        Values are agnostic or single. Default value is single.

      • os_types array[string]

        Use this field to specify the operating system.

        Values are linux, macos, or windows. Default value is [] (empty).

      • tags array[string(nonempty)]

        String array containing words and phrases to help categorize exception items.

        Minimum length of each is 1. Default value is [] (empty).

      • tie_breaker_id string Required

        Field used in search to ensure all containers are sorted and returned correctly.

      • type string Required

        Value is simple.

      • updated_at string(date-time) Required

        Autogenerated date of last object update.

      • updated_by string Required

        Autogenerated value - user that last updated object.

    • page integer Required

      Minimum value is 1.

    • per_page integer Required

      Minimum value is 1.

    • pit string
    • total integer Required

      Minimum value is 0.

  • 400 application/json

    Invalid input data response

    One of:
    Hide attributes Show attributes
  • 401 application/json

    Unsuccessful authentication response

    Hide response attributes Show response attributes object
  • 403 application/json

    Not enough privileges response

    Hide response attributes Show response attributes object
  • 404 application/json

    Exception list not found response

    Hide response attributes Show response attributes object
  • 500 application/json

    Internal server error response

    Hide response attributes Show response attributes object
GET /api/exception_lists/items/_find
curl \
 --request GET https://localhost:5601/api/exception_lists/items/_find?list_id=simple_list
Response examples (200)
{
  "data": [
    {
      "id": "459c5e7e-f8b2-4f0b-b136-c1fc702f72da",
      "name": "Sample Exception List Item",
      "tags": [
        "malware"
      ],
      "type": "simple",
      "entries": [
        {
          "type": "exists",
          "field": "actingProcess.file.signer",
          "operator": "excluded"
        },
        {
          "type": "match_any",
          "field": "host.name",
          "value": [
            "jupiter",
            "saturn"
          ],
          "operator": "included"
        }
      ],
      "item_id": "simple_list_item",
      "list_id": "simple_list",
      "_version": "WzgsMV0=",
      "comments": [],
      "os_types": [
        "linux"
      ],
      "created_at": "2025-01-07T21:12:25.512Z",
      "created_by": "elastic",
      "updated_at": "2025-01-07T21:12:25.512Z",
      "updated_by": "elastic",
      "description": "This is a sample exception item.",
      "namespace_type": "single",
      "tie_breaker_id": "ad0754ff-7b19-49ca-b73e-e6aff6bfa2d0"
    }
  ],
  "page": 1,
  "total": 1,
  "per_page": 20
}
Response examples (400)
{
  "error": "Bad Request",
  "message": "[request query]: namespace_type.0: Invalid enum value. Expected 'agnostic' | 'single', received 'blob'",
  "statusCode": 400
}
Response examples (401)
{
  "error": "Unauthorized",
  "message": "[security_exception\\n\\tRoot causes:\\n\\t\\tsecurity_exception: unable to authenticate user [elastic] for REST request [/_security/_authenticate]]: unable to authenticate user [elastic] for REST request [/_security/_authenticate]",
  "statusCode": 401
}
Response examples (403)
{
  "error": "Forbidden",
  "message": "API [GET /api/exception_lists/items/_find?list_id=simple_list&namespace_type=single] is unauthorized for user, this action is granted by the Kibana privileges [lists-read]",
  "statusCode": 403
}
Response examples (404)
{
  "message": "exception list list_id: \"foo\" does not exist",
  "status_code": 404
}
Response examples (500)
{
  "message": "Internal Server Error",
  "status_code": 500
}