IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

« Delete comments from case API Find connectors API »

› › ›

Find cases API

edit

Find cases API

edit

Retrieves a paginated subset of cases.

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

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": "[email protected]",
        "full_name": "Jane Doe",
        "username": "jdoe"
      },
      "status": "open",
      "updated_at": "2022-05-12T00:27:58.162Z",
      "updated_by": {
        "email": "[email protected]",
        "full_name": "Joe Smith",
        "username": "jsmith"
      },
      "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.

« Delete comments from case API Find connectors API »