IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.
« Find case activity API Find connectors API »
Elastic Docs ›Kibana Guide [8.8] ›REST API ›Cases APIs

Find cases API

edit

Find cases API

edit

Retrieves a paginated subset of cases.

For the most up-to-date API details, refer to the open API specification.

Request

edit

GET <kibana host>:<port>/api/cases/_find

GET <kibana host>:<port>/s/<space_id>/api/cases/_find

Prerequisites

edit

You must have read privileges for the Cases feature in the Management, Observability, or Security section of the Kibana feature privileges, depending on the owner of the cases you’re seeking.

Path parameters

edit
<space_id>
(Optional, string) An identifier for the space. If it is not specified, the default space is used.

Query parameters

edit
assignees
(Optional, string or array of strings) Filters the returned cases by assignees. Valid values are none or unique identifiers for the user profiles. These identifiers can be found by using the suggest user profile API.
defaultSearchOperator
(Optional, string) The default operator to use for the simple_query_string. Defaults to OR.
fields
(Optional, array of strings) The fields in the entity to return in the response.
from
(Optional, string) Returns only cases that were created after a specific date. The date must be specified as a KQL data range or date match expression. [preview] This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.
owner
(Optional, string or array of strings) A filter to limit the retrieved cases to a specific set of applications. Valid values are: cases, observability, and securitySolution. If this parameter is omitted, the response contains all cases that the user has access to read.
page
(Optional, integer) The page number to return. Defaults to 1.
perPage
(Optional, integer) The number of rules to return per page. Defaults to 20.
reporters
(Optional, string or array of strings) Filters the returned cases by the reporter’s username.
search
(Optional, string) An Elasticsearch simple_query_string query that filters the objects in the response.
searchFields
(Optional, string or array of strings) The fields to perform the simple_query_string parsed query against.
severity
(Optional,string) The severity of the case. Valid values are: critical, high, low, and medium.
sortField

(Optional, string) Determines which field is used to sort the results, createdAt or updatedAt. Defaults to createdAt.

Even though the JSON case object uses created_at and updated_at fields, you must use createdAt and updatedAt fields in the URL query.

sortOrder
(Optional, string) Determines the sort order, which can be desc or asc. Defaults to desc.
status
(Optional, string) Filters the returned cases by state, which can be open, in-progress, or closed.
tags
(Optional, string or array of strings) Filters the returned cases by tags.
to
(Optional, string) Returns only cases that were created before a specific date. The date must be specified as a KQL data range or date match expression. [preview] This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.

Response codes

edit
200
Indicates a successful call.

Examples

edit

Retrieve the first five cases with the tag-1 tag, in ascending order by last update time:

GET api/cases/_find?page=1&perPage=5&sortField=updatedAt&sortOrder=asc&tags=tag-1

The API returns a JSON object listing the retrieved cases. For example:

{
  "page": 1,
  "per_page": 5,
  "total": 1,
  "cases": [
    {
      "id": "abed3a70-71bd-11ea-a0b2-c51ea50a58e2",
      "version": "WzExMCwxXQ==",
      "comments": [],
      "totalComment": 1,
      "totalAlerts": 0,
      "title": "Case title",
      "tags": [ "tag-1" ],
      "description": "Case description",
      "settings": { "syncAlerts": true },
      "owner": "securitySolution",
      "duration": null, 
      "severity": "low",
      "closed_at": null,
      "closed_by": null,
      "created_at": "2022-05-12T00:16:36.371Z",
      "created_by": {
        "email": "jdoe@email.com",
        "full_name": "Jane Doe",
        "username": "jdoe"
      },
      "status": "open",
      "updated_at": "2022-05-12T00:27:58.162Z",
      "updated_by": {
        "email": "jsmith@email.com",
        "full_name": "Joe Smith",
        "username": "jsmith"
      },
      "assignees": [],
      "connector": {
        "id": "none",
        "name": "none",
        "type": ".none",
        "fields": null
      },
      "external_service": null
    }
  ],
  "count_open_cases": 1,
  "count_in_progress_cases":0,
  "count_closed_cases": 0
}

Duration represents the elapsed time from the creation of the case to its closure (in seconds). If the case has not been closed, the duration is set to null. If the case was closed after less than half a second, the duration is rounded down to zero.
« Find case activity API Find connectors API »