Elastic Docs ›Kibana Guide ›REST API ›Cases APIs
« Find case activity API Find connectors API »

Find cases APIedit

Retrieves a paginated subset of cases.

For the most up-to-date API details, refer to the open API specification. For a preview, check out Case APIs.

Requestedit

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

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

Prerequisitesedit

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 parametersedit

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

Query parametersedit

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.
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 apply best effort 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 apply best effort to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.

Response codesedit

200
Indicates a successful call.

Examplesedit

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 »