> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trieve.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Search Analytics

> This route allows you to view the search analytics for a dataset.


## OpenAPI

````yaml post /api/analytics/search
openapi: 3.0.3
info:
  title: Trieve API
  description: >-
    Trieve OpenAPI Specification. This document describes all of the operations
    available through the Trieve API.
  contact:
    name: Trieve Team
    url: https://trieve.ai
    email: developers@trieve.ai
  license:
    name: BSL
    url: https://github.com/devflowinc/trieve/blob/main/LICENSE.txt
  version: 0.13.0
servers:
  - url: https://api.trieve.ai
    description: Production server
  - url: http://localhost:8090
    description: Local development server
security: []
tags:
  - name: Invitation
    description: Invitation endpoint. Exists to invite users to an organization.
  - name: Auth
    description: Authentication endpoint. Serves to register and authenticate users.
  - name: User
    description: User endpoint. Enables you to modify user roles and information.
  - name: Organization
    description: >-
      Organization endpoint. Enables you to modify organization roles and
      information.
  - name: Dataset
    description: >-
      Dataset endpoint. Datasets belong to organizations and hold configuration
      information for both client and server. Datasets contain chunks and chunk
      groups.
  - name: Chunk
    description: >-
      Chunk endpoint. Think of chunks as individual searchable units of
      information. The majority of your integration will likely be with the
      Chunk endpoint.
  - name: Chunk Group
    description: >-
      Chunk groups endpoint. Think of a chunk_group as a bookmark folder within
      the dataset.
  - name: Crawl
    description: Crawl endpoint. Used to create and manage crawls for datasets.
  - name: File
    description: >-
      File endpoint. When files are uploaded, they are stored in S3 and broken
      up into chunks with text extraction from Apache Tika. You can upload files
      of pretty much any type up to 1GB in size. See chunking algorithm details
      at `docs.trieve.ai` for more information on how chunking works. Improved
      default chunking is on our roadmap.
  - name: Events
    description: >-
      Notifications endpoint. Files are uploaded asynchronously and events are
      sent to the user when the upload is complete.
  - name: Topic
    description: >-
      Topic chat endpoint. Think of topics as the storage system for gen-ai chat
      memory. Gen AI messages belong to topics.
  - name: Message
    description: >-
      Message chat endpoint. Messages are units belonging to a topic in the
      context of a chat with a LLM. There are system, user, and assistant
      messages.
  - name: Stripe
    description: >-
      Stripe endpoint. Used for the managed SaaS version of this app. Eventually
      this will become a micro-service. Reach out to the team using contact info
      found at `docs.trieve.ai` for more information.
  - name: Health
    description: Health check endpoint. Used to check if the server is up and running.
  - name: Metrics
    description: Metrics endpoint. Used to get information for monitoring
  - name: Analytics
    description: Analytics endpoint. Used to get information for search and RAG analytics
  - name: Experiment
    description: Experiment endpoint. Used to create and manage experiments
paths:
  /api/analytics/search:
    post:
      tags:
        - Analytics
      summary: Get Search Analytics
      description: This route allows you to view the search analytics for a dataset.
      operationId: get_search_analytics
      parameters:
        - name: TR-Dataset
          in: header
          description: >-
            The dataset id or tracking_id to use for the request. We assume you
            intend to use an id if the value is a valid uuid.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        description: JSON request payload to filter the graph
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchAnalytics'
        required: true
      responses:
        '200':
          description: The search analytics for the dataset
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchAnalyticsResponse'
        '400':
          description: Service error relating to getting search analytics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBody'
      security:
        - ApiKey:
            - admin
components:
  schemas:
    SearchAnalytics:
      oneOf:
        - type: object
          title: LatencyGraph
          required:
            - type
          properties:
            filter:
              allOf:
                - $ref: '#/components/schemas/SearchAnalyticsFilter'
              nullable: true
            granularity:
              allOf:
                - $ref: '#/components/schemas/Granularity'
              nullable: true
            type:
              type: string
              enum:
                - latency_graph
        - type: object
          title: SearchUsageGraph
          required:
            - type
          properties:
            filter:
              allOf:
                - $ref: '#/components/schemas/SearchAnalyticsFilter'
              nullable: true
            granularity:
              allOf:
                - $ref: '#/components/schemas/Granularity'
              nullable: true
            type:
              type: string
              enum:
                - search_usage_graph
        - type: object
          title: SearchMetrics
          required:
            - type
          properties:
            filter:
              allOf:
                - $ref: '#/components/schemas/SearchAnalyticsFilter'
              nullable: true
            type:
              type: string
              enum:
                - search_metrics
        - type: object
          title: HeadQueries
          required:
            - type
          properties:
            filter:
              allOf:
                - $ref: '#/components/schemas/SearchAnalyticsFilter'
              nullable: true
            page:
              type: integer
              format: int32
              nullable: true
              minimum: 0
            type:
              type: string
              enum:
                - head_queries
        - type: object
          title: LowConfidenceQueries
          required:
            - type
          properties:
            filter:
              allOf:
                - $ref: '#/components/schemas/SearchAnalyticsFilter'
              nullable: true
            page:
              type: integer
              format: int32
              nullable: true
              minimum: 0
            threshold:
              type: number
              format: float
              nullable: true
            type:
              type: string
              enum:
                - low_confidence_queries
        - type: object
          title: NoResultQueries
          required:
            - type
          properties:
            filter:
              allOf:
                - $ref: '#/components/schemas/SearchAnalyticsFilter'
              nullable: true
            page:
              type: integer
              format: int32
              nullable: true
              minimum: 0
            type:
              type: string
              enum:
                - no_result_queries
        - type: object
          title: SearchQueries
          required:
            - type
          properties:
            filter:
              allOf:
                - $ref: '#/components/schemas/SearchAnalyticsFilter'
              nullable: true
            has_clicks:
              type: boolean
              nullable: true
            page:
              type: integer
              format: int32
              nullable: true
              minimum: 0
            sort_by:
              allOf:
                - $ref: '#/components/schemas/SearchSortBy'
              nullable: true
            sort_order:
              allOf:
                - $ref: '#/components/schemas/SortOrder'
              nullable: true
            type:
              type: string
              enum:
                - search_queries
        - type: object
          title: CountQueries
          required:
            - type
          properties:
            count_collapsed_queries:
              type: boolean
              nullable: true
            filter:
              allOf:
                - $ref: '#/components/schemas/SearchAnalyticsFilter'
              nullable: true
            type:
              type: string
              enum:
                - count_queries
        - type: object
          title: QueryDetails
          required:
            - request_id
            - type
          properties:
            request_id:
              type: string
              format: uuid
            type:
              type: string
              enum:
                - query_details
        - type: object
          title: PopularFilters
          required:
            - type
          properties:
            filter:
              allOf:
                - $ref: '#/components/schemas/SearchAnalyticsFilter'
              nullable: true
            type:
              type: string
              enum:
                - popular_filters
        - type: object
          title: CTRMetricsOverTime
          required:
            - type
          properties:
            filter:
              allOf:
                - $ref: '#/components/schemas/SearchAnalyticsFilter'
              nullable: true
            granularity:
              allOf:
                - $ref: '#/components/schemas/Granularity'
              nullable: true
            type:
              type: string
              enum:
                - ctr_metrics_over_time
        - type: object
          title: SearchConversionRate
          required:
            - type
          properties:
            filter:
              allOf:
                - $ref: '#/components/schemas/SearchAnalyticsFilter'
              nullable: true
            granularity:
              allOf:
                - $ref: '#/components/schemas/Granularity'
              nullable: true
            type:
              type: string
              enum:
                - search_conversion_rate
        - type: object
          title: SearchesPerUser
          required:
            - type
          properties:
            filter:
              allOf:
                - $ref: '#/components/schemas/SearchAnalyticsFilter'
              nullable: true
            granularity:
              allOf:
                - $ref: '#/components/schemas/Granularity'
              nullable: true
            type:
              type: string
              enum:
                - searches_per_user
        - type: object
          title: SearchAverageRating
          required:
            - type
          properties:
            filter:
              allOf:
                - $ref: '#/components/schemas/SearchAnalyticsFilter'
              nullable: true
            granularity:
              allOf:
                - $ref: '#/components/schemas/Granularity'
              nullable: true
            type:
              type: string
              enum:
                - search_average_rating
        - type: object
          title: EventFunnel
          required:
            - type
          properties:
            filter:
              allOf:
                - $ref: '#/components/schemas/SearchAnalyticsFilter'
              nullable: true
            type:
              type: string
              enum:
                - event_funnel
        - type: object
          title: SearchRevenue
          required:
            - type
          properties:
            direct:
              type: boolean
              nullable: true
            filter:
              allOf:
                - $ref: '#/components/schemas/SearchAnalyticsFilter'
              nullable: true
            granularity:
              allOf:
                - $ref: '#/components/schemas/Granularity'
              nullable: true
            type:
              type: string
              enum:
                - search_revenue
      discriminator:
        propertyName: type
    SearchAnalyticsResponse:
      oneOf:
        - $ref: '#/components/schemas/LatencyGraphResponse'
        - $ref: '#/components/schemas/SearchUsageGraphResponse'
        - $ref: '#/components/schemas/DatasetAnalytics'
        - $ref: '#/components/schemas/HeadQueryResponse'
        - $ref: '#/components/schemas/SearchQueryResponse'
        - $ref: '#/components/schemas/SearchQueryResponse'
        - $ref: '#/components/schemas/SearchQueryResponse'
        - $ref: '#/components/schemas/QueryCountResponse'
        - $ref: '#/components/schemas/SearchQueryEvent'
        - $ref: '#/components/schemas/PopularFiltersResponse'
        - $ref: '#/components/schemas/CTRMetricsOverTimeResponse'
        - $ref: '#/components/schemas/SearchConversionRateResponse'
        - $ref: '#/components/schemas/SearchesPerUserResponse'
        - $ref: '#/components/schemas/SearchAverageRatingResponse'
        - $ref: '#/components/schemas/EventNameAndCountsResponse'
        - $ref: '#/components/schemas/SearchRevenueResponse'
    ErrorResponseBody:
      type: object
      required:
        - message
      properties:
        message:
          type: string
      example:
        message: Bad Request
    SearchAnalyticsFilter:
      type: object
      properties:
        component_name:
          type: string
          nullable: true
        date_range:
          allOf:
            - $ref: '#/components/schemas/DateRange'
          nullable: true
        query:
          type: string
          nullable: true
        query_rating:
          allOf:
            - $ref: '#/components/schemas/QueryRatingRange'
          nullable: true
        search_method:
          allOf:
            - $ref: '#/components/schemas/SearchMethod'
          nullable: true
        search_type:
          allOf:
            - $ref: '#/components/schemas/SearchType'
          nullable: true
        top_score:
          allOf:
            - $ref: '#/components/schemas/FloatRange'
          nullable: true
    Granularity:
      type: string
      enum:
        - minute
        - second
        - hour
        - day
        - month
    SearchSortBy:
      type: string
      enum:
        - created_at
        - latency
        - top_score
    SortOrder:
      type: string
      enum:
        - desc
        - asc
    LatencyGraphResponse:
      type: object
      title: LatencyGraphResponse
      required:
        - points
      properties:
        points:
          type: array
          items:
            $ref: '#/components/schemas/FloatTimePoint'
    SearchUsageGraphResponse:
      type: object
      title: SearchUsageGraphResponse
      required:
        - total_searches
        - points
      properties:
        points:
          type: array
          items:
            $ref: '#/components/schemas/IntegerTimePoint'
        total_searches:
          type: integer
          format: int64
    DatasetAnalytics:
      type: object
      title: SearchMetricsResponse
      required:
        - total_queries
        - avg_latency
        - p99
        - p95
        - p50
        - total_positive_ratings
        - total_negative_ratings
      properties:
        avg_latency:
          type: number
          format: double
          description: Average latency of search queries
        p50:
          type: number
          format: double
          description: 50th percentile latency of search queries
        p95:
          type: number
          format: double
          description: 95th percentile latency of search queries
        p99:
          type: number
          format: double
          description: 99th percentile latency of search queries
        total_negative_ratings:
          type: number
          format: double
          description: Total number of searches with a negative rating
        total_positive_ratings:
          type: number
          format: double
          description: Total number of searches with a positive rating
        total_queries:
          type: integer
          format: int64
          description: Total number of search queries
    HeadQueryResponse:
      type: object
      title: HeadQueryResponse
      required:
        - queries
      properties:
        queries:
          type: array
          items:
            $ref: '#/components/schemas/HeadQueries'
    SearchQueryResponse:
      type: object
      title: SearchQueryResponse
      required:
        - queries
      properties:
        queries:
          type: array
          items:
            $ref: '#/components/schemas/SearchQueryEvent'
    QueryCountResponse:
      type: object
      title: QueryCountResponse
      required:
        - total_queries
      properties:
        total_queries:
          type: array
          items:
            $ref: '#/components/schemas/SearchTypeCount'
    SearchQueryEvent:
      type: object
      title: SearchQueryEvent
      required:
        - id
        - search_type
        - query
        - request_params
        - latency
        - top_score
        - results
        - dataset_id
        - created_at
        - user_id
      properties:
        created_at:
          type: string
        dataset_id:
          type: string
          format: uuid
        id:
          type: string
          format: uuid
        latency:
          type: number
          format: float
        metadata:
          nullable: true
        query:
          type: string
        query_rating:
          allOf:
            - $ref: '#/components/schemas/SearchQueryRating'
          nullable: true
        request_params: {}
        results:
          type: array
          items: {}
        search_type:
          $ref: '#/components/schemas/ClickhouseSearchTypes'
        top_score:
          type: number
          format: float
        user_id:
          type: string
    PopularFiltersResponse:
      type: object
      title: PopularFiltersResponse
      required:
        - popular_filters
      properties:
        popular_filters:
          type: array
          items:
            $ref: '#/components/schemas/PopularFilters'
    CTRMetricsOverTimeResponse:
      type: object
      required:
        - total_ctr
        - points
      properties:
        points:
          type: array
          items:
            $ref: '#/components/schemas/FloatTimePoint'
        total_ctr:
          type: number
          format: double
    SearchConversionRateResponse:
      type: object
      required:
        - conversion_rate
        - points
      properties:
        conversion_rate:
          type: number
          format: double
        points:
          type: array
          items:
            $ref: '#/components/schemas/FloatTimePoint'
    SearchesPerUserResponse:
      type: object
      required:
        - avg_searches_per_user
        - points
      properties:
        avg_searches_per_user:
          type: number
          format: double
        points:
          type: array
          items:
            $ref: '#/components/schemas/FloatTimePoint'
    SearchAverageRatingResponse:
      type: object
      required:
        - avg_search_rating
        - points
      properties:
        avg_search_rating:
          type: number
          format: double
        points:
          type: array
          items:
            $ref: '#/components/schemas/FloatTimePoint'
    EventNameAndCountsResponse:
      type: object
      required:
        - event_names
      properties:
        event_names:
          type: array
          items:
            $ref: '#/components/schemas/EventNameAndCounts'
    SearchRevenueResponse:
      type: object
      required:
        - avg_revenue
        - points
      properties:
        avg_revenue:
          type: number
          format: double
        points:
          type: array
          items:
            $ref: '#/components/schemas/FloatTimePoint'
    DateRange:
      type: object
      description: >-
        DateRange is a JSON object which can be used to filter chunks by a range
        of dates. This leverages the time_stamp field on chunks in your dataset.
        You can specify this if you want values in a certain range. You must
        provide ISO 8601 combined date and time without timezone.
      properties:
        gt:
          type: string
          nullable: true
        gte:
          type: string
          nullable: true
        lt:
          type: string
          nullable: true
        lte:
          type: string
          nullable: true
      example:
        gt: '2021-01-01 00:00:00.000'
        gte: '2021-01-01 00:00:00.000'
        lt: '2021-01-01 00:00:00.000'
        lte: '2021-01-01 00:00:00.000'
    QueryRatingRange:
      type: object
      properties:
        gt:
          type: integer
          format: int32
          nullable: true
          minimum: 0
        gte:
          type: integer
          format: int32
          nullable: true
          minimum: 0
        lt:
          type: integer
          format: int32
          nullable: true
          minimum: 0
        lte:
          type: integer
          format: int32
          nullable: true
          minimum: 0
      example:
        gt: 1
        gte: 1
        lt: 1
        lte: 1
    SearchMethod:
      type: string
      enum:
        - fulltext
        - semantic
        - hybrid
        - bm25
    SearchType:
      type: string
      enum:
        - search
        - autocomplete
        - search_over_groups
        - search_within_groups
    FloatRange:
      type: object
      properties:
        gt:
          type: number
          format: double
          nullable: true
        gte:
          type: number
          format: double
          nullable: true
        lt:
          type: number
          format: double
          nullable: true
        lte:
          type: number
          format: double
          nullable: true
    FloatTimePoint:
      type: object
      required:
        - time_stamp
        - point
      properties:
        point:
          type: number
          format: double
        time_stamp:
          type: string
    IntegerTimePoint:
      type: object
      required:
        - time_stamp
        - point
      properties:
        point:
          type: integer
          format: int64
        time_stamp:
          type: string
    HeadQueries:
      type: object
      required:
        - query
        - count
      properties:
        count:
          type: integer
          format: int64
        query:
          type: string
    SearchTypeCount:
      type: object
      required:
        - search_type
        - search_method
        - search_count
      properties:
        search_count:
          type: integer
          format: int64
        search_method:
          type: string
        search_type:
          type: string
      example:
        search_count: 8
        search_type: search
    SearchQueryRating:
      type: object
      required:
        - rating
      properties:
        metadata:
          nullable: true
        note:
          type: string
          nullable: true
        rating:
          type: integer
          format: int32
    ClickhouseSearchTypes:
      type: string
      enum:
        - search
        - search_over_groups
        - autocomplete
        - rag
    PopularFilters:
      type: object
      required:
        - clause
        - field
        - filter_type
        - count
        - common_values
      properties:
        clause:
          type: string
        common_values:
          type: object
          additionalProperties:
            type: integer
            format: int32
            minimum: 0
        count:
          type: integer
          format: int64
        field:
          type: string
        filter_type:
          type: string
      example:
        clause: must
        common_values:
          '130': 2
          '198': 11
        count: 8
        field: metadata.ep_num
        filter_type: match_any
    EventNameAndCounts:
      type: object
      required:
        - event_name
        - event_count
      properties:
        event_count:
          type: integer
          format: int64
        event_name:
          type: string
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: Authorization

````