openapi: 3.2.0
info:
  title: LiteLLM user agent analytics API
  description: "Enterprise Edition \n\nProxy Server to call 100+ LLMs in the OpenAI format. [**Customize Swagger Docs**](https://docs.litellm.ai/docs/proxy/enterprise#swagger-docs---custom-routes--branding)\n\n\U0001F449 [```LiteLLM Admin Panel on /ui```](/ui). Create, Edit Keys with SSO. Having issues? Try [```Fallback Login```](/fallback/login)\n\n\U0001F4B8 [```LiteLLM Model Cost Map```](https://models.litellm.ai/).\n\n\U0001F50E [```LiteLLM Model Hub```](/ui/model_hub_table). See available models on the proxy. [**Docs**](https://docs.litellm.ai/docs/proxy/ai_hub)"
  version: 1.95.0
  x-operator: institution
  x-provenance:
    method: probed
    source: https://llmproxy.uva.nl/openapi.json
    retrieved: '2026-08-19'
    note: Document is generated by the LiteLLM proxy software the University of Amsterdam self-hosts; the deployment, the key issuance and the host (llmproxy.uva.nl, UvA Azure) are the institution's. servers[] added by API Evangelist because the served document omits it; nothing else altered.
servers:
- url: https://llmproxy.uva.nl
  description: University of Amsterdam / Amsterdam University of Applied Sciences shared AI gateway
tags:
- name: user agent analytics
paths:
  /tag/distinct:
    get:
      tags:
      - user agent analytics
      summary: Get Distinct User Agent Tags
      description: "Get all distinct user agent tags up to a maximum of {MAX_TAGS} tags.\n\nThis endpoint returns all unique user agent tags found in the database,\nsorted by frequency of usage.\n\nReturns:\n    DistinctTagsResponse: List of distinct user agent tags"
      operationId: get_distinct_user_agent_tags_tag_distinct_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DistinctTagsResponse'
      security:
      - APIKeyHeader: []
  /tag/dau:
    get:
      tags:
      - user agent analytics
      summary: Get Daily Active Users
      description: "Get Daily Active Users (DAU) by tags for the last {MAX_DAYS} days ending on UTC today + 1 day.\n\nThis endpoint efficiently calculates unique users per tag for each of the last {MAX_DAYS} days\nusing a single optimized SQL query, perfect for dashboard time series visualization.\n\nArgs:\n    tag_filter: Optional filter to specific tag (legacy)\n    tag_filters: Optional filter to multiple specific tags (takes precedence over tag_filter)\n\nReturns:\n    ActiveUsersAnalyticsResponse: DAU data by tag for each of the last {MAX_DAYS} days"
      operationId: get_daily_active_users_tag_dau_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: tag_filter
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by specific tag (optional)
          title: Tag Filter
        description: Filter by specific tag (optional)
      - name: tag_filters
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          description: Filter by multiple specific tags (optional, takes precedence over tag_filter)
          title: Tag Filters
        description: Filter by multiple specific tags (optional, takes precedence over tag_filter)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActiveUsersAnalyticsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /tag/wau:
    get:
      tags:
      - user agent analytics
      summary: Get Weekly Active Users
      description: "Get Weekly Active Users (WAU) by tags for the last {MAX_WEEKS} weeks ending on UTC today + 1 day.\n\nShows week-by-week breakdown:\n- Week 1 (Jan 1): Earliest week (7 weeks ago)\n- Week 2 (Jan 8): Next week (6 weeks ago)\n- Week 3 (Jan 15): Next week (5 weeks ago)\n- ... and so on for {MAX_WEEKS} weeks total\n- Week 7: Most recent week ending on UTC today + 1 day\n\nArgs:\n    tag_filter: Optional filter to specific tag (legacy)\n    tag_filters: Optional filter to multiple specific tags (takes precedence over tag_filter)\n\nReturns:\n    ActiveUsersAnalyticsResponse: WAU data by tag for each of the last {MAX_WEEKS} weeks with descriptive week labels (e.g., \"Week 1 (Jan 1)\")"
      operationId: get_weekly_active_users_tag_wau_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: tag_filter
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by specific tag (optional)
          title: Tag Filter
        description: Filter by specific tag (optional)
      - name: tag_filters
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          description: Filter by multiple specific tags (optional, takes precedence over tag_filter)
          title: Tag Filters
        description: Filter by multiple specific tags (optional, takes precedence over tag_filter)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActiveUsersAnalyticsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /tag/mau:
    get:
      tags:
      - user agent analytics
      summary: Get Monthly Active Users
      description: "Get Monthly Active Users (MAU) by tags for the last {MAX_MONTHS} months ending on UTC today + 1 day.\n\nShows month-by-month breakdown:\n- Month 1 (Nov): Earliest month (7 months ago, 30-day period)\n- Month 2 (Dec): Next month (6 months ago)\n- Month 3 (Jan): Next month (5 months ago)\n- ... and so on for {MAX_MONTHS} months total\n- Month 7: Most recent month ending on UTC today + 1 day\n\nArgs:\n    tag_filter: Optional filter to specific tag (legacy)\n    tag_filters: Optional filter to multiple specific tags (takes precedence over tag_filter)\n\nReturns:\n    ActiveUsersAnalyticsResponse: MAU data by tag for each of the last {MAX_MONTHS} months with descriptive month labels (e.g., \"Month 1 (Nov)\")"
      operationId: get_monthly_active_users_tag_mau_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: tag_filter
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by specific tag (optional)
          title: Tag Filter
        description: Filter by specific tag (optional)
      - name: tag_filters
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          description: Filter by multiple specific tags (optional, takes precedence over tag_filter)
          title: Tag Filters
        description: Filter by multiple specific tags (optional, takes precedence over tag_filter)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActiveUsersAnalyticsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /tag/summary:
    get:
      tags:
      - user agent analytics
      summary: Get Tag Summary
      description: "Get summary analytics for tags including unique users, requests, tokens, and spend.\n\nArgs:\n    start_date: Start date for the analytics period (YYYY-MM-DD)\n    end_date: End date for the analytics period (YYYY-MM-DD)\n    tag_filter: Optional filter to specific tag (legacy)\n    tag_filters: Optional filter to multiple specific tags (takes precedence over tag_filter)\n\nReturns:\n    TagSummaryResponse: Summary analytics data by tag"
      operationId: get_tag_summary_tag_summary_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: start_date
        in: query
        required: true
        schema:
          type: string
          description: Start date in YYYY-MM-DD format
          title: Start Date
        description: Start date in YYYY-MM-DD format
      - name: end_date
        in: query
        required: true
        schema:
          type: string
          description: End date in YYYY-MM-DD format
          title: End Date
        description: End date in YYYY-MM-DD format
      - name: tag_filter
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by specific tag (optional)
          title: Tag Filter
        description: Filter by specific tag (optional)
      - name: tag_filters
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          description: Filter by multiple specific tags (optional, takes precedence over tag_filter)
          title: Tag Filters
        description: Filter by multiple specific tags (optional, takes precedence over tag_filter)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TagSummaryResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /tag/user-agent/per-user-analytics:
    get:
      tags:
      - user agent analytics
      summary: Get Per User Analytics
      description: "Get per-user analytics including successful requests, tokens, and spend by individual users.\n\nThis endpoint provides usage metrics broken down by individual users based on their\ntag activity during the last 30 days ending on UTC today + 1 day.\n\nArgs:\n    tag_filter: Optional filter to specific tag (legacy)\n    tag_filters: Optional filter to multiple specific tags (takes precedence over tag_filter)\n    page: Page number for pagination\n    page_size: Number of items per page\n\nReturns:\n    PerUserAnalyticsResponse: Analytics data broken down by individual users for the last 30 days"
      operationId: get_per_user_analytics_tag_user_agent_per_user_analytics_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: tag_filter
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by specific tag (optional)
          title: Tag Filter
        description: Filter by specific tag (optional)
      - name: tag_filters
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          description: Filter by multiple specific tags (optional, takes precedence over tag_filter)
          title: Tag Filters
        description: Filter by multiple specific tags (optional, takes precedence over tag_filter)
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          description: Page number for pagination
          default: 1
          title: Page
        description: Page number for pagination
      - name: page_size
        in: query
        required: false
        schema:
          type: integer
          maximum: 1000
          minimum: 1
          description: Items per page
          default: 50
          title: Page Size
        description: Items per page
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PerUserAnalyticsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    TagActiveUsersResponse:
      properties:
        tag:
          type: string
          title: Tag
        active_users:
          type: integer
          title: Active Users
        date:
          type: string
          title: Date
        period_start:
          anyOf:
          - type: string
          - type: 'null'
          title: Period Start
        period_end:
          anyOf:
          - type: string
          - type: 'null'
          title: Period End
      type: object
      required:
      - tag
      - active_users
      - date
      title: TagActiveUsersResponse
      description: Response for tag active users metrics
    TagSummaryMetrics:
      properties:
        tag:
          type: string
          title: Tag
        unique_users:
          type: integer
          title: Unique Users
        total_requests:
          type: integer
          title: Total Requests
        successful_requests:
          type: integer
          title: Successful Requests
        failed_requests:
          type: integer
          title: Failed Requests
        total_tokens:
          type: integer
          title: Total Tokens
        total_spend:
          type: number
          title: Total Spend
      type: object
      required:
      - tag
      - unique_users
      - total_requests
      - successful_requests
      - failed_requests
      - total_tokens
      - total_spend
      title: TagSummaryMetrics
      description: Summary metrics for a tag
    DistinctTagsResponse:
      properties:
        results:
          items:
            $ref: '#/components/schemas/DistinctTagResponse'
          type: array
          title: Results
      type: object
      required:
      - results
      title: DistinctTagsResponse
      description: Response for all distinct user agent tags
    ActiveUsersAnalyticsResponse:
      properties:
        results:
          items:
            $ref: '#/components/schemas/TagActiveUsersResponse'
          type: array
          title: Results
      type: object
      required:
      - results
      title: ActiveUsersAnalyticsResponse
      description: Response for active users analytics
    TagSummaryResponse:
      properties:
        results:
          items:
            $ref: '#/components/schemas/TagSummaryMetrics'
          type: array
          title: Results
      type: object
      required:
      - results
      title: TagSummaryResponse
      description: Response for tag summary analytics
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    PerUserAnalyticsResponse:
      properties:
        results:
          items:
            $ref: '#/components/schemas/PerUserMetrics'
          type: array
          title: Results
        total_count:
          type: integer
          title: Total Count
        page:
          type: integer
          title: Page
        page_size:
          type: integer
          title: Page Size
        total_pages:
          type: integer
          title: Total Pages
      type: object
      required:
      - results
      - total_count
      - page
      - page_size
      - total_pages
      title: PerUserAnalyticsResponse
      description: Response for per-user analytics
    DistinctTagResponse:
      properties:
        tag:
          type: string
          title: Tag
      type: object
      required:
      - tag
      title: DistinctTagResponse
      description: Response for distinct user agent tags
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    PerUserMetrics:
      properties:
        user_id:
          type: string
          title: User Id
        user_email:
          anyOf:
          - type: string
          - type: 'null'
          title: User Email
        user_agent:
          anyOf:
          - type: string
          - type: 'null'
          title: User Agent
        successful_requests:
          type: integer
          title: Successful Requests
          default: 0
        failed_requests:
          type: integer
          title: Failed Requests
          default: 0
        total_requests:
          type: integer
          title: Total Requests
          default: 0
        total_tokens:
          type: integer
          title: Total Tokens
          default: 0
        spend:
          type: number
          title: Spend
          default: 0.0
      type: object
      required:
      - user_id
      title: PerUserMetrics
      description: Metrics for individual user
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      description: Bearer token
      in: header
      name: x-litellm-api-key