Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Elasticsearch Analytics API
license:
name: Apache 2.0
url: https://github.com/elastic/elasticsearch-specification/blob/main/LICENSE
version: ''
description: 'Elasticsearch provides REST APIs that are used by the UI components and can be called directly to configure and access Elasticsearch features.
## Documentation source and versions
This documentation is derived from the `main` branch of the elasticsearch-specification repository. It is provided under license Attribution-NonCommercial-NoDerivatives 4.0 International.
This documentation contains work-in-progress information for future Elastic Stack releases.'
x-doc-license:
name: Attribution-NonCommercial-NoDerivatives 4.0 International
url: https://creativecommons.org/licenses/by-nc-nd/4.0/
x-feedbackLink:
label: Feedback
url: https://github.com/elastic/docs-content/issues/new?assignees=&labels=feedback%2Ccommunity&projects=&template=api-feedback.yaml&title=%5BFeedback%5D%3A+
security:
- apiKeyAuth: []
- basicAuth: []
- bearerAuth: []
tags:
- name: Analytics
x-displayName: Behavioral analytics
description: The behavioral analytics APIs let you create and manage analytics collections and view their data. Use them to analyze users’ search and click behavior, improve result relevance, and identify content gaps.
paths:
/_application/analytics/{name}:
get:
tags:
- Analytics
summary: Get behavioral analytics collections
description: '**All methods and paths for this operation:**
GET
/_application/analytics
GET
/_application/analytics/{name}'
operationId: search-application-get-behavioral-analytics
parameters:
- $ref: '#/components/parameters/search_application.get_behavioral_analytics-name'
responses:
'200':
$ref: '#/components/responses/search_application.get_behavioral_analytics-200'
deprecated: true
x-state: Experimental; Added in 8.8.0
x-codeSamples:
- lang: Console
source: 'GET _application/analytics/my*
'
- lang: Python
source: "resp = client.search_application.get_behavioral_analytics(\n name=\"my*\",\n)"
- lang: JavaScript
source: "const response = await client.searchApplication.getBehavioralAnalytics({\n name: \"my*\",\n});"
- lang: Ruby
source: "response = client.search_application.get_behavioral_analytics(\n name: \"my*\"\n)"
- lang: PHP
source: "$resp = $client->searchApplication()->getBehavioralAnalytics([\n \"name\" => \"my*\",\n]);"
- lang: curl
source: 'curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_application/analytics/my*"'
- lang: C#
source: "var response = await client.SearchApplication\n .GetBehavioralAnalyticsAsync(d1 => d1\n .Name([\"my*\"])\n );"
- lang: Java
source: "client.searchApplication().getBehavioralAnalytics(g -> g\n .name(\"my*\")\n);\n"
x-metaTags:
- content: Elasticsearch
name: product_name
put:
tags:
- Analytics
summary: Create a behavioral analytics collection
operationId: search-application-put-behavioral-analytics
parameters:
- in: path
name: name
description: The name of the analytics collection to be created or updated.
required: true
deprecated: false
schema:
$ref: '#/components/schemas/_types.Name'
style: simple
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/search_application.put_behavioral_analytics.AnalyticsAcknowledgeResponseBase'
deprecated: true
x-state: Experimental; Added in 8.8.0
x-codeSamples:
- lang: Console
source: 'PUT _application/analytics/my_analytics_collection
'
- lang: Python
source: "resp = client.search_application.put_behavioral_analytics(\n name=\"my_analytics_collection\",\n)"
- lang: JavaScript
source: "const response = await client.searchApplication.putBehavioralAnalytics({\n name: \"my_analytics_collection\",\n});"
- lang: Ruby
source: "response = client.search_application.put_behavioral_analytics(\n name: \"my_analytics_collection\"\n)"
- lang: PHP
source: "$resp = $client->searchApplication()->putBehavioralAnalytics([\n \"name\" => \"my_analytics_collection\",\n]);"
- lang: curl
source: 'curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_application/analytics/my_analytics_collection"'
- lang: C#
source: 'var response = await client.SearchApplication.PutBehavioralAnalyticsAsync(name: "my_analytics_collection");'
- lang: Java
source: "client.searchApplication().putBehavioralAnalytics(p -> p\n .name(\"my_analytics_collection\")\n);\n"
x-metaTags:
- content: Elasticsearch
name: product_name
delete:
tags:
- Analytics
summary: Delete a behavioral analytics collection
description: The associated data stream is also deleted.
operationId: search-application-delete-behavioral-analytics
parameters:
- in: path
name: name
description: The name of the analytics collection to be deleted
required: true
deprecated: false
schema:
$ref: '#/components/schemas/_types.Name'
style: simple
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/_types.AcknowledgedResponseBase'
deprecated: true
x-state: Experimental; Added in 8.8.0
x-codeSamples:
- lang: Console
source: 'DELETE _application/analytics/my_analytics_collection/
'
- lang: Python
source: "resp = client.search_application.delete_behavioral_analytics(\n name=\"my_analytics_collection\",\n)"
- lang: JavaScript
source: "const response = await client.searchApplication.deleteBehavioralAnalytics({\n name: \"my_analytics_collection\",\n});"
- lang: Ruby
source: "response = client.search_application.delete_behavioral_analytics(\n name: \"my_analytics_collection\"\n)"
- lang: PHP
source: "$resp = $client->searchApplication()->deleteBehavioralAnalytics([\n \"name\" => \"my_analytics_collection\",\n]);"
- lang: curl
source: 'curl -X DELETE -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_application/analytics/my_analytics_collection/"'
- lang: C#
source: 'var response = await client.SearchApplication.DeleteBehavioralAnalyticsAsync(name: "my_analytics_collection");'
- lang: Java
source: "client.searchApplication().deleteBehavioralAnalytics(d -> d\n .name(\"my_analytics_collection\")\n);\n"
x-metaTags:
- content: Elasticsearch
name: product_name
/_application/analytics/{collection_name}/event/{event_type}:
post:
tags:
- Analytics
summary: Create a behavioral analytics collection event
externalDocs:
description: About behavioral analytics events
url: https://www.elastic.co/guide/en/elasticsearch/reference/8.19/behavioral-analytics-event-reference.html
x-previousVersionUrl: https://www.elastic.co/guide/en/elasticsearch/reference/8.19/post-analytics-collection-event.html
operationId: search-application-post-behavioral-analytics-event
parameters:
- in: path
name: collection_name
description: The name of the behavioral analytics collection.
required: true
deprecated: false
schema:
$ref: '#/components/schemas/_types.Name'
style: simple
- in: path
name: event_type
description: The analytics event type.
required: true
deprecated: false
schema:
$ref: '#/components/schemas/search_application._types.EventType'
style: simple
- in: query
name: debug
description: Whether the response type has to include more details
deprecated: false
schema:
type: boolean
style: form
requestBody:
content:
application/json:
schema:
type: object
examples:
BehavioralAnalyticsEventPostRequestExample1:
description: Run `POST _application/analytics/my_analytics_collection/event/search_click` to send a `search_click` event to an analytics collection called `my_analytics_collection`.
value: "{\n \"session\": {\n \"id\": \"1797ca95-91c9-4e2e-b1bd-9c38e6f386a9\"\n },\n \"user\": {\n \"id\": \"5f26f01a-bbee-4202-9298-81261067abbd\"\n },\n \"search\":{\n \"query\": \"search term\",\n \"results\": {\n \"items\": [\n {\n \"document\": {\n \"id\": \"123\",\n \"index\": \"products\"\n }\n }\n ],\n \"total_results\": 10\n },\n \"sort\": {\n \"name\": \"relevance\"\n },\n \"search_application\": \"website\"\n },\n \"document\":{\n \"id\": \"123\",\n \"index\": \"products\"\n }\n}"
required: true
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
accepted:
type: boolean
event:
type: object
required:
- accepted
deprecated: true
x-state: Experimental
x-codeSamples:
- lang: Console
source: "POST _application/analytics/my_analytics_collection/event/search_click\n{\n \"session\": {\n \"id\": \"1797ca95-91c9-4e2e-b1bd-9c38e6f386a9\"\n },\n \"user\": {\n \"id\": \"5f26f01a-bbee-4202-9298-81261067abbd\"\n },\n \"search\":{\n \"query\": \"search term\",\n \"results\": {\n \"items\": [\n {\n \"document\": {\n \"id\": \"123\",\n \"index\": \"products\"\n }\n }\n ],\n \"total_results\": 10\n },\n \"sort\": {\n \"name\": \"relevance\"\n },\n \"search_application\": \"website\"\n },\n \"document\":{\n \"id\": \"123\",\n \"index\": \"products\"\n }\n}"
- lang: Python
source: "resp = client.search_application.post_behavioral_analytics_event(\n collection_name=\"my_analytics_collection\",\n event_type=\"search_click\",\n payload={\n \"session\": {\n \"id\": \"1797ca95-91c9-4e2e-b1bd-9c38e6f386a9\"\n },\n \"user\": {\n \"id\": \"5f26f01a-bbee-4202-9298-81261067abbd\"\n },\n \"search\": {\n \"query\": \"search term\",\n \"results\": {\n \"items\": [\n {\n \"document\": {\n \"id\": \"123\",\n \"index\": \"products\"\n }\n }\n ],\n \"total_results\": 10\n },\n \"sort\": {\n \"name\": \"relevance\"\n },\n \"search_application\": \"website\"\n },\n \"document\": {\n \"id\": \"123\",\n \"index\": \"products\"\n }\n },\n)"
- lang: JavaScript
source: "const response = await client.searchApplication.postBehavioralAnalyticsEvent({\n collection_name: \"my_analytics_collection\",\n event_type: \"search_click\",\n payload: {\n session: {\n id: \"1797ca95-91c9-4e2e-b1bd-9c38e6f386a9\",\n },\n user: {\n id: \"5f26f01a-bbee-4202-9298-81261067abbd\",\n },\n search: {\n query: \"search term\",\n results: {\n items: [\n {\n document: {\n id: \"123\",\n index: \"products\",\n },\n },\n ],\n total_results: 10,\n },\n sort: {\n name: \"relevance\",\n },\n search_application: \"website\",\n },\n document: {\n id: \"123\",\n index: \"products\",\n },\n },\n});"
- lang: Ruby
source: "response = client.search_application.post_behavioral_analytics_event(\n collection_name: \"my_analytics_collection\",\n event_type: \"search_click\",\n body: {\n \"session\": {\n \"id\": \"1797ca95-91c9-4e2e-b1bd-9c38e6f386a9\"\n },\n \"user\": {\n \"id\": \"5f26f01a-bbee-4202-9298-81261067abbd\"\n },\n \"search\": {\n \"query\": \"search term\",\n \"results\": {\n \"items\": [\n {\n \"document\": {\n \"id\": \"123\",\n \"index\": \"products\"\n }\n }\n ],\n \"total_results\": 10\n },\n \"sort\": {\n \"name\": \"relevance\"\n },\n \"search_application\": \"website\"\n },\n \"document\": {\n \"id\": \"123\",\n \"index\": \"products\"\n }\n }\n)"
- lang: PHP
source: "$resp = $client->searchApplication()->postBehavioralAnalyticsEvent([\n \"collection_name\" => \"my_analytics_collection\",\n \"event_type\" => \"search_click\",\n \"body\" => [\n \"session\" => [\n \"id\" => \"1797ca95-91c9-4e2e-b1bd-9c38e6f386a9\",\n ],\n \"user\" => [\n \"id\" => \"5f26f01a-bbee-4202-9298-81261067abbd\",\n ],\n \"search\" => [\n \"query\" => \"search term\",\n \"results\" => [\n \"items\" => array(\n [\n \"document\" => [\n \"id\" => \"123\",\n \"index\" => \"products\",\n ],\n ],\n ),\n \"total_results\" => 10,\n ],\n \"sort\" => [\n \"name\" => \"relevance\",\n ],\n \"search_application\" => \"website\",\n ],\n \"document\" => [\n \"id\" => \"123\",\n \"index\" => \"products\",\n ],\n ],\n]);"
- lang: curl
source: 'curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d ''{"session":{"id":"1797ca95-91c9-4e2e-b1bd-9c38e6f386a9"},"user":{"id":"5f26f01a-bbee-4202-9298-81261067abbd"},"search":{"query":"search term","results":{"items":[{"document":{"id":"123","index":"products"}}],"total_results":10},"sort":{"name":"relevance"},"search_application":"website"},"document":{"id":"123","index":"products"}}'' "$ELASTICSEARCH_URL/_application/analytics/my_analytics_collection/event/search_click"'
- lang: C#
source: "var response = await client.SearchApplication\n .PostBehavioralAnalyticsEventAsync(collectionName: \"my_analytics_collection\", eventType: EventType.SearchClick, d1 => d1\n .Payload(JsonSerializer.Deserialize<JsonElement>(\"\"\"\n {\n \"session\": {\n \"id\": \"1797ca95-91c9-4e2e-b1bd-9c38e6f386a9\"\n },\n \"user\": {\n \"id\": \"5f26f01a-bbee-4202-9298-81261067abbd\"\n },\n \"search\": {\n \"query\": \"search term\",\n \"results\": {\n \"items\": [\n {\n \"document\": {\n \"id\": \"123\",\n \"index\": \"products\"\n }\n }\n ],\n \"total_results\": 10\n },\n \"sort\": {\n \"name\": \"relevance\"\n },\n \"search_application\": \"website\"\n },\n \"document\": {\n \"id\": \"123\",\n \"index\": \"products\"\n }\n }\n \"\"\"))\n );"
- lang: Java
source: "client.searchApplication().postBehavioralAnalyticsEvent(p -> p\n .collectionName(\"my_analytics_collection\")\n .eventType(EventType.SearchClick)\n .payload(JsonData.fromJson(\"\"\"\n{\"session\":{\"id\":\"1797ca95-91c9-4e2e-b1bd-9c38e6f386a9\"},\"user\":{\"id\":\"5f26f01a-bbee-4202-9298-81261067abbd\"},\"search\":{\"query\":\"search term\",\"results\":{\"items\":[{\"document\":{\"id\":\"123\",\"index\":\"products\"}}],\"total_results\":10},\"sort\":{\"name\":\"relevance\"},\"search_application\":\"website\"},\"document\":{\"id\":\"123\",\"index\":\"products\"}}\n\"\"\"))\n);\n"
x-metaTags:
- content: Elasticsearch
name: product_name
components:
schemas:
search_application._types.EventDataStream:
type: object
properties:
name:
allOf:
- $ref: '#/components/schemas/_types.IndexName'
required:
- name
_types.AcknowledgedResponseBase:
type: object
properties:
acknowledged:
description: For a successful response, this value is always true. On failure, an exception is returned instead.
type: boolean
required:
- acknowledged
_types.IndexName:
type: string
_types.Name:
type: string
search_application._types.EventType:
type: string
enum:
- page_view
- search
- search_click
search_application._types.AnalyticsCollection:
type: object
properties:
event_data_stream:
description: Data stream for the collection.
allOf:
- $ref: '#/components/schemas/search_application._types.EventDataStream'
required:
- event_data_stream
search_application.put_behavioral_analytics.AnalyticsAcknowledgeResponseBase:
allOf:
- $ref: '#/components/schemas/_types.AcknowledgedResponseBase'
- type: object
properties:
name:
description: The name of the analytics collection created or updated
allOf:
- $ref: '#/components/schemas/_types.Name'
required:
- name
responses:
search_application.get_behavioral_analytics-200:
description: ''
content:
application/json:
schema:
type: object
additionalProperties:
$ref: '#/components/schemas/search_application._types.AnalyticsCollection'
examples:
BehavioralAnalyticsGetResponseExample1:
description: A successful response from `GET _application/analytics/my*`
value: "{\n \"my_analytics_collection\": {\n \"event_data_stream\": {\n \"name\": \"behavioral_analytics-events-my_analytics_collection\"\n }\n },\n \"my_analytics_collection2\": {\n \"event_data_stream\": {\n \"name\": \"behavioral_analytics-events-my_analytics_collection2\"\n }\n }\n}"
parameters:
search_application.get_behavioral_analytics-name:
in: path
name: name
description: A list of analytics collections to limit the returned information
required: true
deprecated: false
schema:
type: array
items:
$ref: '#/components/schemas/_types.Name'
style: simple
securitySchemes:
apiKeyAuth:
in: header
name: Authorization
type: apiKey
description: "Elasticsearch APIs support key-based authentication.\nYou must create an API key and use the encoded value in the request header.\nFor example:\n\n\n```\ncurl -X GET \"${ES_URL}/_cat/indices?v=true\" \\\n -H \"Authorization: ApiKey ${API_KEY}\"\n```\n\nTo get API keys, use the `/_security/api_key` APIs.\n"
basicAuth:
scheme: basic
type: http
bearerAuth:
scheme: bearer
type: http
description: 'Elasticsearch APIs support the use of bearer tokens in the `Authorization` HTTP header to authenticate with the API.
For examples, refer to [Token-based authentication services](https://www.elastic.co/docs/deploy-manage/users-roles/cluster-or-deployment-auth/token-based-authentication-services)
'
x-provenance:
method: harvested
publisher: Anomaly Detection
source: https://www.elastic.co/docs/api/doc/elasticsearch/group/elasticsearch-openapi-source.json
note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
stamped by stamp-openapi-provenance.py (roadmap#793)