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

# Execute an analytics query



## OpenAPI

````yaml openapi.json post /api/analytics.query
openapi: 3.0.3
info:
  title: Staminads API
  description: Web analytics platform for tracking TimeScore metrics
  version: 1.0.0
servers:
  - url: https://your-instance.example.com
    description: Your Staminads instance
security: []
paths:
  /api/analytics.query:
    post:
      tags:
        - analytics
      summary: Execute an analytics query
      operationId: AnalyticsController_query
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnalyticsQueryDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
components:
  schemas:
    AnalyticsQueryDto:
      type: object
      properties:
        workspace_id:
          type: string
        metrics:
          minItems: 1
          type: array
          items:
            type: string
        dimensions:
          type: array
          items:
            type: string
        filters:
          type: array
          items:
            $ref: '#/components/schemas/FilterDto'
        metricFilters:
          type: array
          items:
            $ref: '#/components/schemas/MetricFilterDto'
        dateRange:
          $ref: '#/components/schemas/DateRangeDto'
        compareDateRange:
          $ref: '#/components/schemas/DateRangeDto'
        timezone:
          type: string
        order:
          type: object
        limit:
          type: number
          minimum: 1
          maximum: 10000
        havingMinSessions:
          type: number
          minimum: 1
        table:
          type: string
          enum:
            - sessions
            - pages
            - goals
        totalsGroupBy:
          description: >-
            When set, enables "filtered totals" mode for queries with no
            dimensions.

            The query will:

            1. Group by these dimensions in an inner subquery

            2. Apply metricFilters via HAVING clause

            3. Aggregate the filtered results in an outer query


            Use this for totals that should respect metricFilters.

            Example: Get total sessions where bounce_rate > 50%, grouped by
            landing_path.
          type: array
          items:
            type: string
      required:
        - workspace_id
        - metrics
        - dateRange
    FilterDto:
      type: object
      properties:
        dimension:
          type: string
        operator:
          type: string
          enum:
            - equals
            - notEquals
            - in
            - notIn
            - contains
            - notContains
            - gt
            - gte
            - lt
            - lte
            - isNull
            - isNotNull
            - between
            - isEmpty
            - isNotEmpty
        values:
          type: array
          items:
            type: object
      required:
        - dimension
        - operator
    MetricFilterDto:
      type: object
      properties:
        metric:
          type: string
        operator:
          type: string
          enum:
            - gt
            - gte
            - lt
            - lte
            - between
        values:
          type: array
          items:
            type: object
      required:
        - metric
        - operator
        - values
    DateRangeDto:
      type: object
      properties:
        start:
          type: string
        end:
          type: string
        preset:
          type: string
          enum:
            - previous_30_minutes
            - today
            - yesterday
            - previous_7_days
            - previous_14_days
            - previous_28_days
            - previous_30_days
            - previous_90_days
            - previous_91_days
            - this_week
            - previous_week
            - this_month
            - previous_month
            - this_quarter
            - previous_quarter
            - this_year
            - previous_year
            - previous_12_months
            - all_time
        granularity:
          type: string
          enum:
            - hour
            - day
            - week
            - month
            - year

````