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

# Engagement & activity



## OpenAPI

````yaml /openapi/user.yaml get /api/v1/analytics/engagement
openapi: 3.0.3
info:
  title: CapeMedia User Service API
  version: 1.0.0
  description: |2-

        **CapeMedia User Service API** - Comprehensive user service and management system.

        ## Authentication
        This API uses **JWT Bearer tokens** for authentication.

        1. Login via `/api/v1/auth/login` to obtain tokens
        2. Include the access token in the `Authorization` header: `Bearer <access_token>`
        3. Refresh expired tokens via `/api/v1/auth/refresh-token`

        ## Versioning
        The API uses URL path versioning (e.g., `/api/v1/`, `/api/v2/`).
        Current version: **v1**
        
  contact:
    name: API Support
    email: support@capemedia.co.ke
  license:
    name: Cape Media
servers:
  - url: https://api.diginacape.co.ke/acl
    description: Production
  - url: http://localhost:8000
    description: Local
security: []
paths:
  /api/v1/analytics/engagement:
    get:
      tags:
        - Analytics
      summary: Engagement & activity
      operationId: analytics_engagement_retrieve
      parameters:
        - in: query
          name: realm
          schema:
            type: string
          description: Keycloak realm
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EngagementResponse'
          description: ''
      security:
        - bearerAuth: []
components:
  schemas:
    EngagementResponse:
      type: object
      description: Full ``APIResponse`` envelope for the engagement endpoint.
      properties:
        success:
          type: boolean
        message:
          type: string
        data:
          $ref: '#/components/schemas/_Data'
      required:
        - data
        - message
        - success
    _Data:
      type: object
      description: Engagement payload returned under ``data`` by the engagement endpoint.
      properties:
        dau:
          type: integer
          description: >-
            Daily Active Users — active (is_active) users who logged in within
            the last 24 hours.
        wau:
          type: integer
          description: Weekly Active Users — logged in within the last 7 days.
        mau:
          type: integer
          description: Monthly Active Users — logged in within the last 30 days.
        stickiness_pct:
          type: number
          format: double
          description: >-
            Stickiness = DAU ÷ MAU as a percentage. The share of monthly-active
            users who return on a given day; higher means more habitual daily
            usage. e.g. 5.1 ≈ 1 in 20 monthly users active today.
        recency_buckets:
          $ref: '#/components/schemas/RecencyBuckets'
        department_activity:
          type: array
          items:
            $ref: '#/components/schemas/DepartmentActivity'
      required:
        - dau
        - department_activity
        - mau
        - recency_buckets
        - stickiness_pct
        - wau
    RecencyBuckets:
      type: object
      description: |-
        Active users grouped by how recently they last logged in.

        Buckets are mutually exclusive and together sum to the total active-user
        count. Each value is a headcount, derived from ``User.last_login``.
      properties:
        today:
          type: integer
          description: Last login within the past 24 hours.
        this_week:
          type: integer
          description: Last login 1–7 days ago (excludes today).
        this_month:
          type: integer
          description: Last login 7–30 days ago (excludes this week).
        over_90_days:
          type: integer
          description: Last login more than 90 days ago — dormant.
        never:
          type: integer
          description: Never logged in (last_login is null) — provisioned but unused.
        30_to_90_days:
          type: integer
          description: Last login 30–90 days ago — going dormant.
      required:
        - 30_to_90_days
        - never
        - over_90_days
        - this_month
        - this_week
        - today
    DepartmentActivity:
      type: object
      description: Per-department headcount and 30-day activity.
      properties:
        department:
          type: string
          description: Department name, or "Unassigned".
        headcount:
          type: integer
          description: Total users in the department.
        active_30d:
          type: integer
          description: Users who logged in within the last 30 days.
        activation_pct:
          type: number
          format: double
          description: active_30d ÷ headcount as a percentage.
      required:
        - activation_pct
        - active_30d
        - department
        - headcount
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Enter your JWT token in the format: Bearer <token>'

````