> ## 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 Analytics

> This route allows you to view the analytics for a dataset using a structured query.



## OpenAPI

````yaml post /api/analytics
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:
    post:
      tags:
        - Analytics
      summary: Get Analytics
      description: >-
        This route allows you to view the analytics for a dataset using a
        structured query.
      operationId: get_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/AnalyticsQuery'
        required: true
      responses:
        '200':
          description: The analytics for the dataset
          content:
            application/json:
              schema: {}
      security:
        - ApiKey:
            - admin
components:
  schemas:
    AnalyticsQuery:
      type: object
      description: Represents a complete Analytics query with parameters
      required:
        - columns
        - table
      properties:
        columns:
          type: array
          items:
            $ref: '#/components/schemas/Column'
          description: Simple columns to select
        cte_query:
          allOf:
            - $ref: '#/components/schemas/CommonTableExpression'
          nullable: true
        expressions:
          type: array
          items:
            $ref: '#/components/schemas/Expression'
          description: Complex expressions to select
          nullable: true
        filter_conditions:
          type: array
          items:
            $ref: '#/components/schemas/FilterCondition'
          description: WHERE clause conditions
          nullable: true
        group_by:
          allOf:
            - $ref: '#/components/schemas/GroupBy'
          nullable: true
        joins:
          type: array
          items:
            $ref: '#/components/schemas/JoinClause'
          description: Tables to join with
          nullable: true
        limit:
          type: integer
          format: int32
          description: LIMIT clause
          nullable: true
          minimum: 0
        offset:
          type: integer
          format: int32
          description: OFFSET clause
          nullable: true
          minimum: 0
        order_by:
          allOf:
            - $ref: '#/components/schemas/OrderBy'
          nullable: true
        table:
          $ref: '#/components/schemas/TableName'
    Column:
      type: object
      description: Represents a column with optional aggregation and alias
      required:
        - name
      properties:
        aggregation:
          allOf:
            - $ref: '#/components/schemas/AggregationType'
          nullable: true
        alias:
          type: string
          nullable: true
        distinct:
          type: boolean
          nullable: true
        name:
          type: string
    CommonTableExpression:
      type: object
      required:
        - alias
        - query
      properties:
        alias:
          type: string
        query:
          $ref: '#/components/schemas/SubQuery'
    Expression:
      type: object
      description: Represents a SQL expression with optional alias
      required:
        - expression
      properties:
        alias:
          type: string
          nullable: true
        expression:
          $ref: '#/components/schemas/ExpressionType'
    FilterCondition:
      type: object
      description: Represents a query filter condition
      required:
        - column
        - operator
        - value
      properties:
        and_filter:
          type: array
          items:
            $ref: '#/components/schemas/FilterCondition'
          nullable: true
        column:
          type: string
        operator:
          $ref: '#/components/schemas/FilterOperator'
        or_filter:
          type: array
          items:
            $ref: '#/components/schemas/FilterCondition'
          nullable: true
        value:
          $ref: '#/components/schemas/FilterValue'
    GroupBy:
      type: object
      description: Represents a GROUP BY clause
      required:
        - columns
      properties:
        columns:
          type: array
          items:
            type: string
        having:
          allOf:
            - $ref: '#/components/schemas/HavingCondition'
          nullable: true
    JoinClause:
      type: object
      description: Represents a join between tables
      required:
        - table
        - condition
      properties:
        condition:
          $ref: '#/components/schemas/JoinCondition'
        join_type:
          allOf:
            - $ref: '#/components/schemas/JoinType'
          nullable: true
        table:
          $ref: '#/components/schemas/TableName'
    OrderBy:
      type: object
      required:
        - columns
      properties:
        columns:
          type: array
          items:
            type: string
        direction:
          allOf:
            - $ref: '#/components/schemas/Direction'
          nullable: true
    TableName:
      oneOf:
        - type: string
          enum:
            - search_queries
        - type: string
          enum:
            - rag_queries
        - type: string
          enum:
            - recommendations
        - type: string
          enum:
            - events
        - type: string
          enum:
            - cluster_topics
        - type: string
          enum:
            - search_cluster_memberships
        - type: string
          enum:
            - topics
        - type: string
          enum:
            - experiments
        - type: string
          enum:
            - experiment_user_assignments
        - type: object
          required:
            - Custom
          properties:
            Custom:
              type: string
    AggregationType:
      type: string
      enum:
        - SUM
        - COUNT
        - AVG
        - MIN
        - MAX
    SubQuery:
      type: object
      description: Represents a complete ClickHouse query with parameters
      required:
        - columns
        - table
      properties:
        columns:
          type: array
          items:
            $ref: '#/components/schemas/Column'
          description: Simple columns to select
        expressions:
          type: array
          items:
            $ref: '#/components/schemas/Expression'
          description: Complex expressions to select
          nullable: true
        filter_conditions:
          type: array
          items:
            $ref: '#/components/schemas/FilterCondition'
          description: WHERE clause conditions
          nullable: true
        group_by:
          allOf:
            - $ref: '#/components/schemas/GroupBy'
          nullable: true
        joins:
          type: array
          items:
            $ref: '#/components/schemas/JoinClause'
          description: Tables to join with
          nullable: true
        limit:
          type: integer
          format: int32
          description: LIMIT clause
          nullable: true
          minimum: 0
        offset:
          type: integer
          format: int32
          description: OFFSET clause
          nullable: true
          minimum: 0
        order_by:
          allOf:
            - $ref: '#/components/schemas/OrderBy'
          nullable: true
        table:
          $ref: '#/components/schemas/TableName'
    ExpressionType:
      oneOf:
        - type: object
          required:
            - name
            - type
          properties:
            name:
              type: string
            type:
              type: string
              enum:
                - column
        - type: object
          required:
            - value
            - type
          properties:
            type:
              type: string
              enum:
                - literal
            value:
              $ref: '#/components/schemas/FilterValue'
        - type: object
          required:
            - name
            - args
            - type
          properties:
            args:
              type: array
              items:
                $ref: '#/components/schemas/ExpressionType'
            name:
              type: string
            type:
              type: string
              enum:
                - function
        - type: object
          required:
            - sql
            - type
          properties:
            sql:
              type: string
            type:
              type: string
              enum:
                - raw
      description: Structured expression type
      discriminator:
        propertyName: type
    FilterOperator:
      type: string
      enum:
        - '='
        - '!='
        - <>
        - '>'
        - <
        - '>='
        - <=
        - like
        - not like
        - in
        - not in
        - is null
        - is not null
    FilterValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: boolean
        - type: array
          items:
            $ref: '#/components/schemas/FilterValue'
    HavingCondition:
      oneOf:
        - type: object
          required:
            - function
            - column
            - operator
            - value
            - type
          properties:
            column:
              type: string
            function:
              $ref: '#/components/schemas/AggregationType'
            operator:
              $ref: '#/components/schemas/FilterOperator'
            type:
              type: string
              enum:
                - aggregate
            value:
              $ref: '#/components/schemas/FilterValue'
        - type: object
          required:
            - conditions
            - type
          properties:
            conditions:
              type: array
              items:
                $ref: '#/components/schemas/HavingCondition'
            type:
              type: string
              enum:
                - and
        - type: object
          required:
            - conditions
            - type
          properties:
            conditions:
              type: array
              items:
                $ref: '#/components/schemas/HavingCondition'
            type:
              type: string
              enum:
                - or
      description: Structured HAVING condition
      discriminator:
        propertyName: type
    JoinCondition:
      oneOf:
        - type: object
          required:
            - left_column
            - right_column
            - type
          properties:
            left_column:
              type: string
            right_column:
              type: string
            type:
              type: string
              enum:
                - column_equals
        - type: object
          required:
            - columns
            - type
          properties:
            columns:
              type: array
              items:
                type: string
            type:
              type: string
              enum:
                - using
      description: Structured join condition instead of raw SQL
      discriminator:
        propertyName: type
    JoinType:
      type: string
      description: Represents the type of join between tables
      enum:
        - inner
        - left
        - right
        - full
        - cross
        - anti
    Direction:
      type: string
      enum:
        - asc
        - desc
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: Authorization

````