2018-05-30 18:27:48 +02:00
[[saved-objects-api-find]]
2019-09-06 18:09:57 +02:00
=== Find objects API
++++
<titleabbrev>Find objects</titleabbrev>
++++
2018-05-30 18:27:48 +02:00
2019-09-18 17:54:28 +02:00
experimental[] Retrieve a paginated set of {kib} saved objects by various conditions.
2018-12-05 22:20:58 +01:00
2019-09-06 18:09:57 +02:00
[[saved-objects-api-find-request]]
2018-05-30 18:27:48 +02:00
==== Request
2020-03-20 22:33:20 +01:00
`GET <kibana host>:<port>/api/saved_objects/_find`
2018-05-30 18:27:48 +02:00
2020-03-20 22:33:20 +01:00
`GET <kibana host>:<port>/s/<space_id>/api/saved_objects/_find`
2019-10-18 19:17:54 +02:00
[[saved-objects-api-find-path-params]]
==== Path parameters
`space_id`::
(Optional, string) An identifier for the space. If `space_id` is not provided in the URL, the default space is used.
2019-09-06 18:09:57 +02:00
[[saved-objects-api-find-query-params]]
2018-05-30 18:27:48 +02:00
==== Query Parameters
2019-09-06 18:09:57 +02:00
`type`::
(Required, array|string) The saved object types to include in the export.
2019-10-18 19:17:54 +02:00
2019-09-06 18:09:57 +02:00
`per_page`::
(Optional, number) The number of objects to return per page.
2019-10-18 19:17:54 +02:00
2019-09-06 18:09:57 +02:00
`page`::
(Optional, number) The page of objects to return.
2019-10-18 19:17:54 +02:00
2019-09-06 18:09:57 +02:00
`search`::
(Optional, string) An Elasticsearch {ref}/query-dsl-simple-query-string-query.html[simple_query_string] query that filters the objects in the response.
2019-10-18 19:17:54 +02:00
2019-09-06 18:09:57 +02:00
`default_search_operator`::
(Optional, string) The default operator to use for the `simple_query_string`.
2019-10-18 19:17:54 +02:00
2019-09-06 18:09:57 +02:00
`search_fields`::
(Optional, array|string) The fields to perform the `simple_query_string` parsed query against.
2019-10-18 19:17:54 +02:00
2019-09-06 18:09:57 +02:00
`fields`::
2020-07-14 20:43:08 +02:00
(Optional, array|string) The fields to return in the `attributes` key of the response.
2019-10-18 19:17:54 +02:00
2019-09-06 18:09:57 +02:00
`sort_field`::
2020-08-26 22:52:29 +02:00
(Optional, string) Sorts the response. Includes "root" and "type" fields. "root" fields exist for all saved objects, such as "updated_at".
"type" fields are specific to an object type, such as fields returned in the `attributes` key of the response. When a single type is
defined in the `type` parameter, the "root" and "type" fields are allowed, and validity checks are made in that order. When multiple types
are defined in the `type` parameter, only "root" fields are allowed.
2019-10-18 19:17:54 +02:00
2019-09-06 18:09:57 +02:00
`has_reference`::
(Optional, object) Filters to objects that have a relationship with the type and ID combination.
2019-10-03 00:23:44 +02:00
`filter`::
2021-04-16 10:40:30 +02:00
(Optional, string) The filter is a KQL string with the caveat that if you filter with an attribute from your saved object type,
it should look like that: `savedObjectType.attributes.title: "myTitle"`. However, If you use a root attribute of a saved
object such as `updated_at`, you will have to define your filter like that: `savedObjectType.updated_at > 2018-12-22`.
`aggs`::
(Optional, string) **experimental** An aggregation structure, serialized as a string. The field format is similar to `filter`, meaning
that to use a saved object type attribute in the aggregation, the `savedObjectType.attributes.title`: "myTitle"` format
must be used. For root fields, the syntax is `savedObjectType.rootField`
2019-10-03 00:23:44 +02:00
2019-09-06 18:09:57 +02:00
NOTE: As objects change in {kib}, the results on each page of the response also
change. Use the find API for traditional paginated results, but avoid using it to export large amounts of data.
[[saved-objects-api-find-request-codes]]
==== Response code
2019-10-18 19:17:54 +02:00
`200`::
2019-09-06 18:09:57 +02:00
Indicates a successful call.
2018-05-30 18:27:48 +02:00
==== Examples
2019-09-06 18:09:57 +02:00
Find index patterns with titles that start with `my`:
2018-05-30 18:27:48 +02:00
2020-03-20 22:33:20 +01:00
[source,sh]
2018-05-30 18:27:48 +02:00
--------------------------------------------------
2020-07-14 21:59:21 +02:00
$ curl -X GET api/saved_objects/_find?type=index-pattern&search_fields=title&search=my*
2018-05-30 18:27:48 +02:00
--------------------------------------------------
// KIBANA
2019-09-06 18:09:57 +02:00
The API returns the following:
2018-05-30 18:27:48 +02:00
2020-03-20 22:33:20 +01:00
[source,sh]
2018-05-30 18:27:48 +02:00
--------------------------------------------------
{
"total": 1,
"data": [
{
"id": "my-pattern",
"type": "index-pattern",
"version": 1,
"attributes": {
"title": "my-pattern-*"
}
}
]
}
--------------------------------------------------
2019-09-06 18:09:57 +02:00
For parameters that accept multiple values (e.g. `fields`), repeat the
2018-05-30 18:27:48 +02:00
query parameter for each value:
2020-03-20 22:33:20 +01:00
[source,sh]
2018-05-30 18:27:48 +02:00
--------------------------------------------------
2020-07-14 21:59:21 +02:00
$ curl -X GET api/saved_objects/_find?fields=id&fields=title
2018-05-30 18:27:48 +02:00
--------------------------------------------------
// KIBANA