openapi: 3.2.0
info:
  title: Elasticsearch Analytics API
  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.'
  license:
    name: Apache 2.0
    url: https://github.com/elastic/elasticsearch-specification/blob/main/LICENSE
  version: ''
security:
- apiKeyAuth: []
- basicAuth: []
- bearerAuth: []
tags:
- name: 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.
  x-displayName: Behavioral analytics
paths:
  /_application/analytics/{name}:
    get:
      tags:
      - Analytics
      summary: Get behavioral analytics collections
      operationId: search-application-get-behavioral-analytics-1
      parameters:
      - 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
      responses:
        '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}"
      deprecated: true
      x-state: Technical preview; Added in 8.8.0
      x-variations:
      - "<div>\n              <span class=\"operation-verb get\">GET</span>\n              <span class=\"operation-path\">/_application/analytics/{name}</span>\n              </div>\n            "
      x-api: get_behavioral_analytics.search_application
      x-category: management
      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: 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: Technical preview; Added in 8.8.0
      x-variations:
      - "<div>\n              <span class=\"operation-verb put\">PUT</span>\n              <span class=\"operation-path\">/_application/analytics/{name}</span>\n              </div>\n            "
      x-api: put_behavioral_analytics.search_application
      x-category: management
      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: 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: Technical preview; Added in 8.8.0
      x-variations:
      - "<div>\n              <span class=\"operation-verb delete\">DELETE</span>\n              <span class=\"operation-path\">/_application/analytics/{name}</span>\n              </div>\n            "
      x-api: delete_behavioral_analytics.search_application
      x-category: management
      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: Java
        source: "client.searchApplication().deleteBehavioralAnalytics(d -> d\n    .name(\"my_analytics_collection\")\n);\n"
      x-metaTags:
      - content: Elasticsearch
        name: product_name
  /_application/analytics:
    get:
      tags:
      - Analytics
      summary: Get behavioral analytics collections
      operationId: search-application-get-behavioral-analytics
      responses:
        '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}"
      deprecated: true
      x-state: Technical preview; Added in 8.8.0
      x-variations:
      - "<div>\n              <span class=\"operation-verb get\">GET</span>\n              <span class=\"operation-path\">/_application/analytics</span>\n              </div>\n            "
      x-api: get_behavioral_analytics.search_application
      x-category: management
      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: Java
        source: "client.searchApplication().getBehavioralAnalytics(g -> g\n    .name(\"my*\")\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:
        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: Technical preview
      x-variations:
      - "<div>\n              <span class=\"operation-verb post\">POST</span>\n              <span class=\"operation-path\">/_application/analytics/{collection_name}/event/{event_type}</span>\n              </div>\n            "
      x-api: post_behavioral_analytics_event.search_application
      x-category: management
      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: Java
        source: "client.searchApplication().postBehavioralAnalyticsEvent(p -> p\n    .collectionName(\"my_analytics_collection\")\n    .eventType(EventType.SearchClick)\n    .payload(JsonData.fromJson(\"{\\\"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"
      x-metaTags:
      - content: Elasticsearch
        name: product_name
components:
  schemas:
    _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
    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._types.EventDataStream:
      type: object
      properties:
        name:
          allOf:
          - $ref: '#/components/schemas/_types.IndexName'
      required:
      - name
    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
    _types.IndexName:
      type: string
    _types.Name:
      type: string
    search_application._types.EventType:
      type: string
      enum:
      - page_view
      - search
      - search_click
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      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```\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."
    basicAuth:
      type: http
      scheme: basic
    bearerAuth:
      type: http
      scheme: bearer
      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-tagGroups:
- name: AI & Machine Learning
  tags:
  - analytics
  - graph
  - inference
  - ml
  - ml anomaly
  - ml data frame
  - ml trained model
  - query_rules
  - text_structure
- name: Cluster Management
  tags:
  - ccr
  - cluster
  - connector
  - data stream
  - ilm
  - indices
  - rollup
  - script
  - search_application
  - searchable_snapshots
  - slm
  - snapshot
- name: Data Processing
  tags:
  - enrich
  - fleet
  - ingest
  - logstash
  - synonyms
  - transform
- name: Information & Monitoring
  tags:
  - cat
  - features
  - health_report
  - info
  - license
  - migration
  - tasks
  - watcher
  - xpack
- name: Search & Document APIs
  tags:
  - document
  - eql
  - esql
  - search
  - sql
- name: Security
  tags:
  - security