Elastic Stack (ELK Stack) Significant Events API

openapi: 3.2.0
info:
  contact:
    name: Kibana Team
  description: The Kibana REST APIs enable you to manage resources such as connectors, data views, and saved objects.
  title: Kibana Significant Events API
  version: ''
  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+
servers:
- url: https://{kibana_url}
  variables:
    kibana_url:
      default: localhost:5601
security:
- apiKeyAuth: []
- basicAuth: []
tags:
- name: significant_events
  x-displayName: Significant Events
paths:
  /api/streams/{name}/queries:
    get:
      deprecated: true
      description: '**Spaces method and path for this operation:**


        get /s/{space_id}/api/streams/{name}/queries


        Refer to Spaces for more information.


        Fetches all queries linked to a stream that are visible to the current user in the current space.


        [Required authorization] Route required privileges: read_stream.'
      operationId: get-streams-name-queries
      parameters:
      - description: The name of the stream.
        in: path
        name: name
        required: true
        schema:
          maxLength: 255
          type: string
      requestBody:
        content:
          application/json:
            examples: {}
            schema:
              anyOf:
              - additionalProperties: false
                type: object
                properties: {}
              - {}
      responses:
        '200':
          content:
            application/json:
              examples:
                listQueries:
                  value:
                    queries:
                    - description: Count error-level log events grouped by host name
                      esql:
                        query: FROM logs.nginx | WHERE log.level == "error" | STATS count = COUNT(*) BY host.name
                      id: error-count-by-host
                      severity_score: 75
                      title: Error count by host
                      type: match
                    - description: Requests with response time above 2 seconds
                      esql:
                        query: FROM logs.nginx | WHERE http.response_time > 2000
                      id: high-latency-requests
                      severity_score: 50
                      title: High latency requests
                      type: match
          description: List of queries linked to the stream.
      summary: Get stream queries
      tags:
      - significant_events
      x-state: Experimental; added in 9.1.0
      x-metaTags:
      - content: Kibana
        name: product_name
  /api/streams/{name}/queries/_bulk:
    post:
      deprecated: true
      description: '**Spaces method and path for this operation:**


        post /s/{space_id}/api/streams/{name}/queries/_bulk


        Refer to Spaces for more information.


        Bulk update queries of a stream. Can add new queries and delete existing ones.


        [Required authorization] Route required privileges: manage_stream.'
      operationId: post-streams-name-queries-bulk
      parameters:
      - description: A required header to protect against CSRF attacks
        in: header
        name: kbn-xsrf
        required: true
        schema:
          example: 'true'
          type: string
      - description: The name of the stream.
        in: path
        name: name
        required: true
        schema:
          maxLength: 255
          type: string
      requestBody:
        content:
          application/json:
            examples:
              bulkQueries:
                value:
                  operations:
                  - index:
                      description: Count error-level log events grouped by host name
                      esql:
                        query: FROM logs* | WHERE log.level == "error" | STATS count = COUNT(*) BY host.name
                      id: error-count-by-host
                      title: Error count by host
                  - delete:
                      id: old-query-id
            schema:
              additionalProperties: false
              type: object
              properties:
                operations:
                  items:
                    anyOf:
                    - type: object
                      properties:
                        index:
                          type: object
                          properties:
                            description:
                              default: ''
                              maxLength: 10000
                              type: string
                            esql:
                              type: object
                              properties:
                                query:
                                  maxLength: 10000
                                  type: string
                              required:
                              - query
                            evidence:
                              items:
                                maxLength: 10000
                                type: string
                              type: array
                            expires_at:
                              format: date-time
                              pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                              type: string
                            id:
                              description: A non-empty string.
                              minLength: 1
                              type: string
                            severity_score:
                              type: number
                            title:
                              description: A non-empty string.
                              minLength: 1
                              type: string
                          required:
                          - title
                          - esql
                          - id
                      required:
                      - index
                    - type: object
                      properties:
                        delete:
                          type: object
                          properties:
                            id:
                              maxLength: 255
                              type: string
                          required:
                          - id
                      required:
                      - delete
                  type: array
              required:
              - operations
      responses:
        '200':
          description: Bulk operation completed successfully.
      summary: Bulk update queries
      tags:
      - significant_events
      x-state: Experimental; added in 9.1.0
      x-metaTags:
      - content: Kibana
        name: product_name
  /api/streams/{name}/queries/{queryId}:
    delete:
      deprecated: true
      description: '**Spaces method and path for this operation:**


        delete /s/{space_id}/api/streams/{name}/queries/{queryId}


        Refer to Spaces for more information.


        Remove a query from a stream. Noop if the query is not found on the stream.


        [Required authorization] Route required privileges: manage_stream.'
      operationId: delete-streams-name-queries-queryid
      parameters:
      - description: A required header to protect against CSRF attacks
        in: header
        name: kbn-xsrf
        required: true
        schema:
          example: 'true'
          type: string
      - description: The name of the stream.
        in: path
        name: name
        required: true
        schema:
          maxLength: 255
          type: string
      - description: The identifier of the query to remove.
        in: path
        name: queryId
        required: true
        schema:
          maxLength: 255
          type: string
      requestBody:
        content:
          application/json:
            examples: {}
            schema:
              anyOf:
              - additionalProperties: false
                type: object
                properties: {}
              - {}
      responses:
        '200':
          description: The query was removed successfully.
      summary: Remove a query from a stream
      tags:
      - significant_events
      x-state: Experimental; added in 9.1.0
      x-metaTags:
      - content: Kibana
        name: product_name
    put:
      deprecated: true
      description: '**Spaces method and path for this operation:**


        put /s/{space_id}/api/streams/{name}/queries/{queryId}


        Refer to Spaces for more information.


        Adds a query to a stream. Noop if the query is already present on the stream.


        [Required authorization] Route required privileges: manage_stream.'
      operationId: put-streams-name-queries-queryid
      parameters:
      - description: A required header to protect against CSRF attacks
        in: header
        name: kbn-xsrf
        required: true
        schema:
          example: 'true'
          type: string
      - description: The name of the stream.
        in: path
        name: name
        required: true
        schema:
          maxLength: 255
          type: string
      - description: The identifier of the query.
        in: path
        name: queryId
        required: true
        schema:
          maxLength: 255
          type: string
      requestBody:
        content:
          application/json:
            examples:
              upsertQuery:
                value:
                  description: Count error-level log events grouped by host name
                  esql:
                    query: FROM logs* | WHERE log.level == "error" | STATS count = COUNT(*) BY host.name
                  title: Error count by host
            schema:
              additionalProperties: false
              type: object
              properties:
                description:
                  default: ''
                  maxLength: 10000
                  type: string
                esql:
                  additionalProperties: false
                  type: object
                  properties:
                    query:
                      maxLength: 10000
                      type: string
                  required:
                  - query
                evidence:
                  items:
                    maxLength: 10000
                    type: string
                  type: array
                expires_at:
                  format: date-time
                  pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                  type: string
                severity_score:
                  type: number
                title:
                  description: A non-empty string.
                  minLength: 1
                  type: string
              required:
              - title
              - esql
      responses:
        '200':
          description: The query was added or updated successfully.
      summary: Upsert a query to a stream
      tags:
      - significant_events
      x-state: Experimental; added in 9.1.0
      x-metaTags:
      - content: Kibana
        name: product_name
  /api/streams/{name}/significant_events:
    get:
      deprecated: true
      description: '**Spaces method and path for this operation:**


        get /s/{space_id}/api/streams/{name}/significant_events


        Refer to Spaces for more information.


        Read the significant events


        [Required authorization] Route required privileges: read_stream.'
      operationId: get-streams-name-significant-events
      parameters:
      - description: The name of the stream.
        in: path
        name: name
        required: true
        schema:
          maxLength: 255
          type: string
      - description: Start of the time range as an ISO 8601 date string.
        in: query
        name: from
        required: true
        schema:
          maxLength: 255
          type: string
      - description: End of the time range as an ISO 8601 date string.
        in: query
        name: to
        required: true
        schema:
          maxLength: 255
          type: string
      - description: The bucket size for aggregating events (e.g. "1m", "1h").
        in: query
        name: bucketSize
        required: true
        schema:
          maxLength: 255
          pattern: ^(\d+)([smhd])$
          type: string
      - description: Query string to filter significant events on metadata fields
        in: query
        name: query
        required: false
        schema:
          maxLength: 10000
          type: string
      - description: 'Search mode: keyword (BM25), semantic (vector), or hybrid (RRF). When omitted, defaults to hybrid with a silent keyword fallback on failure. When set explicitly, failures propagate as errors.'
        in: query
        name: searchMode
        required: false
        schema:
          enum:
          - keyword
          - semantic
          - hybrid
          type: string
      requestBody:
        content:
          application/json:
            examples: {}
            schema:
              anyOf:
              - additionalProperties: false
                type: object
                properties: {}
              - {}
      responses:
        '200':
          content:
            application/json:
              examples:
                queryOccurrences:
                  value:
                    aggregated_occurrences:
                    - count: 42
                      date: '2025-01-15T10:00:00.000Z'
                    - count: 18
                      date: '2025-01-15T11:00:00.000Z'
                    - count: 7
                      date: '2025-01-15T12:00:00.000Z'
                    queries:
                    - change_points:
                        type:
                          spike:
                            change_point: 1
                            p_value: 0.002
                      description: Count error-level log events grouped by host name
                      esql:
                        query: FROM logs.nginx | WHERE log.level == "error" | STATS count = COUNT(*) BY host.name
                      id: error-count-by-host
                      occurrences:
                      - count: 42
                        date: '2025-01-15T10:00:00.000Z'
                      - count: 18
                        date: '2025-01-15T11:00:00.000Z'
                      - count: 7
                        date: '2025-01-15T12:00:00.000Z'
                      rule_backed: false
                      rule_uuid: 9fdfcf5a-4e1d-5ee3-b05d-7bc2b014e81c
                      severity_score: 75
                      stream_name: logs.nginx
                      title: Error count by host
                      type: match
          description: Significant events for the stream.
      summary: Read the significant events
      tags:
      - significant_events
      x-state: Experimental; added in 9.1.0
      x-metaTags:
      - content: Kibana
        name: product_name
components:
  securitySchemes:
    apiKeyAuth:
      description: 'These APIs use key-based authentication. You must create an API key and use the encoded value in the request header. For example: `Authorization: ApiKey base64AccessApiKey`

        '
      in: header
      name: Authorization
      type: apiKey
    basicAuth:
      scheme: basic
      type: http
x-topics:
- title: Kibana spaces
  content: "Spaces enable you to organize your dashboards and other saved objects into meaningful categories.\nYou can use the default space or create your own spaces.\n\nTo run APIs in non-default spaces, you must add `s/{space_id}/` to the path.\nFor example:\n\n```bash\ncurl -X GET \"http://${KIBANA_URL}/s/marketing/api/data_views\" \\\n  -H \"Authorization: ApiKey ${API_KEY}\"\n```\n\nIf you use the Kibana console to send API requests, it automatically adds the appropriate space identifier.\n\nTo learn more, check out [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces).\n"