> ## Documentation Index
> Fetch the complete documentation index at: https://superwhisper-docs-cloud-model-rate-limits.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Get paginated statistics

> Returns time-series usage statistics with optional grouping, filtering, and pagination. Supports JSON and CSV output formats.



## OpenAPI

````yaml https://api.superwhisper.com/api/v1/openapi.json get /api/v1/stats
openapi: 3.1.0
info:
  title: SuperWhisper API
  version: 1.0.0
  description: Public API for accessing SuperWhisper organization data.
servers:
  - url: https://api.superwhisper.com
    description: Production
security:
  - bearerAuth: []
paths:
  /api/v1/stats:
    get:
      tags:
        - Stats
      summary: Get paginated statistics
      description: >-
        Returns time-series usage statistics with optional grouping, filtering,
        and pagination. Supports JSON and CSV output formats.
      parameters:
        - name: start_date
          in: query
          required: false
          description: ISO 8601 start date (defaults to 7 days ago)
          schema:
            type: string
            pattern: >-
              ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:?\d{2})?)?$
        - name: end_date
          in: query
          required: false
          description: ISO 8601 end date (defaults to now)
          schema:
            type: string
            pattern: >-
              ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:?\d{2})?)?$
        - name: granularity
          in: query
          required: false
          description: Time bucket granularity (defaults to day)
          schema:
            enum:
              - hour
              - day
              - week
              - month
        - name: group_by
          in: query
          required: false
          description: Dimension to group results by
          schema:
            enum:
              - member_email
              - voice_model
              - language_model
              - app_name
        - name: page
          in: query
          required: false
          description: Page number (defaults to 1)
          schema:
            type: integer
            minimum: 1
        - name: page_size
          in: query
          required: false
          description: Results per page, max 1000 (defaults to 200)
          schema:
            type: integer
            minimum: 1
            maximum: 1000
        - name: format
          in: query
          required: false
          description: Response format (defaults to json)
          schema:
            enum:
              - json
              - csv
        - name: filter[member_email]
          in: query
          required: false
          description: Comma-separated member email addresses
          schema:
            type: string
        - name: filter[voice_model]
          in: query
          required: false
          description: Comma-separated voice models
          schema:
            type: string
        - name: filter[language_model]
          in: query
          required: false
          description: Comma-separated language models
          schema:
            type: string
        - name: filter[app_name]
          in: query
          required: false
          description: Comma-separated app names
          schema:
            type: string
      responses:
        '200':
          description: Paginated statistics (or CSV file when format=csv)
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        time_bucket:
                          type: string
                          description: Start of the time period (ISO 8601)
                        recording_count:
                          type: number
                          description: Number of recordings in this period
                        total_words:
                          type: number
                          description: Total words transcribed
                        total_duration:
                          type: number
                          description: Total duration in milliseconds
                        avg_llm_processing_time:
                          type: number
                          description: Average LLM processing time in milliseconds
                        avg_voice_processing_time:
                          type: number
                          description: Average voice processing time in milliseconds
                        avg_wpm:
                          type: number
                          description: Average words per minute
                      required:
                        - time_bucket
                        - recording_count
                        - total_words
                        - total_duration
                        - avg_llm_processing_time
                        - avg_voice_processing_time
                        - avg_wpm
                  pagination:
                    type: object
                    properties:
                      page:
                        type: number
                        description: Current page number
                      page_size:
                        type: number
                        description: Number of results per page
                      total_rows:
                        type: number
                        description: Total number of results
                      total_pages:
                        type: number
                        description: Total number of pages
                      count:
                        type: number
                        description: Number of results returned in this page
                    required:
                      - page
                      - page_size
                      - total_rows
                      - total_pages
                      - count
                  meta:
                    type: object
                    properties:
                      start_date:
                        type: string
                        description: Query start date
                      end_date:
                        type: string
                        description: Query end date
                      granularity:
                        type: string
                        description: Time bucket granularity used
                      group_by:
                        anyOf:
                          - type: string
                          - type: 'null'
                        description: Grouping dimension used, if any
                    required:
                      - start_date
                      - end_date
                      - granularity
                      - group_by
                required:
                  - data
                  - pagination
                  - meta
                $schema: http://json-schema.org/draft-07/schema#
        '400':
          description: Invalid parameters
        '401':
          description: Unauthorized — missing or invalid bearer token
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API access token (starts with sk-sw-)

````