Get value list items

GET /api/lists/items/_find

Get all value list items in the specified list.

Query parameters

  • list_id string(nonempty) Required

    Value list's identifier.

    Minimum length is 1.

  • page integer

    The page number to return.

  • per_page integer

    The number of list items to return per page.

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

  • cursor string(nonempty)

    Returns the items that come after the last item returned in the previous call (use the cursor value returned in the previous call). This parameter uses the tie_breaker_id field to ensure all items are sorted and returned correctly.

    Minimum length is 1.

  • filter string

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

Responses

  • 200 application/json

    Successful response

    Hide response attributes Show response attributes object
    • cursor string(nonempty) Required

      Returns the items that come after the last item returned in the previous call (use the cursor value returned in the previous call). This parameter uses the tie_breaker_id field to ensure all items are sorted and returned correctly.

      Minimum length is 1.

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

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

      • @timestamp string(date-time)
      • created_at string(date-time) Required

        Autogenerated date of object creation.

      • created_by string Required

        Autogenerated value - user that created object.

      • Determines how retrieved list item values are presented. By default list items are presented using these Handelbar expressions:

        • {{{value}}} - Single value item types, such as ip, long, date, keyword, and text.
        • {{{gte}}}-{{{lte}}} - Range value item types, such as ip_range, double_range, float_range, integer_range, and long_range.
        • {{{gte}}},{{{lte}}} - Date range values.
      • id string(nonempty) Required

        Value list item's identifier.

        Minimum length is 1.

      • list_id string(nonempty) Required

        Value list's identifier.

        Minimum length is 1.

      • meta object

        Placeholder for metadata about the value list item.

        Additional properties are allowed.

      • Determines how uploaded list item values are parsed. By default, list items are parsed using these named regex groups:

        • (?<value>.+) - Single value item types, such as ip, long, date, keyword, and text.
        • (?<gte>.+)-(?<lte>.+)|(?<value>.+) - Range value item types, such as date_range, ip_range, double_range, float_range, integer_range, and long_range.
      • tie_breaker_id string Required

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

      • type string Required

        Specifies the Elasticsearch data type of excludes the list container holds. Some common examples:

        • keyword: Many ECS fields are Elasticsearch keywords
        • ip: IP addresses
        • ip_range: Range of IP addresses (supports IPv4, IPv6, and CIDR notation)

        Values are binary, boolean, byte, date, date_nanos, date_range, double, double_range, float, float_range, geo_point, geo_shape, half_float, integer, integer_range, ip, ip_range, keyword, long, long_range, shape, short, or text.

      • updated_at string(date-time) Required

        Autogenerated date of last object update.

      • updated_by string Required

        Autogenerated value - user that last updated object.

      • value string(nonempty) Required

        The value used to evaluate exceptions.

        Minimum length is 1.

    • page integer Required

      Minimum value is 0.

    • per_page integer Required

      Minimum value is 0.

    • 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
  • 500 application/json

    Internal server error response

    Hide response attributes Show response attributes object
GET /api/lists/items/_find
curl \
 --request GET https://localhost:5601/api/lists/items/_find?list_id=21b01cfb-058d-44b9-838c-282be16c91cd
Response examples (200)
{
  "data": [
    {
      "id": "21b01cfb-058d-44b9-838c-282be16c91cc",
      "type": "ip",
      "value": "127.0.0.1",
      "list_id": "ip_list",
      "_version": "WzAsMV0=",
      "@timestamp": "2025-01-08T04:59:06.154Z",
      "created_at": "2025-01-08T04:59:06.154Z",
      "created_by": "elastic",
      "updated_at": "2025-01-08T04:59:06.154Z",
      "updated_by": "elastic",
      "tie_breaker_id": "b57c762c-3036-465c-9bfb-7bfb5e6e515a"
    }
  ],
  "page": 1,
  "total": 1,
  "cursor": "WzIwLFsiYjU3Yzc2MmMtMzAzNi00NjVjLTliZmItN2JmYjVlNmU1MTVhIl1d",
  "per_page": 20
}
Response examples (400)
{
  "error": "Bad Request,",
  "message": "[request query]: list_id: Required",
  "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/lists/items/_find?list_id=ip_list&page=1&per_page=20] is unauthorized for user, this action is granted by the Kibana privileges [lists-read]",
  "statusCode": 403
}
Response examples (500)
{
  "message": "Internal Server Error",
  "status_code": 500
}