Query-trend analytics

GET /analytics/query-trends supplies the internal Public Query Trend Analysis dashboard. It aggregates only queries captured after this feature was deployed; existing conversation history is intentionally not classified or backfilled.

The route requires the configured API key. When verified principal enforcement is enabled, only admin and operator principals are authorized; a verified user receives 403. Browser clients should use a same-origin BFF and must not expose the shared API key.

Request

GET /analytics/query-trends?keyword_limit=10
X-API-Key: <shared API key>
X-User-Subject: <verified subject UUID>
X-User-Role: operator

keyword_limit is optional, defaults to 10, and accepts integers from 1 through 50.

Response

{
  "tracked_queries": 24,
  "classified_queries": 23,
  "unclassified_queries": 1,
  "source_attributed_queries": 19,
  "categories": [
    {"name": "Regulasi & Hukum", "query_count": 9, "share": 0.375},
    {"name": "Layanan Publik", "query_count": 5, "share": 0.20833333333333334}
  ],
  "sources": [
    {"name": "JDIH", "query_count": 12, "share": 0.5},
    {"name": "PPID", "query_count": 4, "share": 0.16666666666666666}
  ],
  "keywords": [
    {"keyword": "qanun", "query_count": 7},
    {"keyword": "anggaran", "query_count": 4}
  ],
  "tracking_started_at": "2026-10-07T04:05:00Z",
  "tracking_through_at": "2026-10-07T07:30:00Z"
}

The categories array always contains the client's six fixed domains, including zero-count rows:

• Regulasi & Hukum
• Layanan Publik
• Anggaran & Keuangan
• Perencanaan & Tata Ruang
• Data Statistik
• Umum & Sapaan

Category assignment is a separate self-hosted model judgment over each new query. An unavailable or malformed judgment is counted under unclassified_queries; the service does not guess a category and does not fail an otherwise valid answer.

Source counts represent distinct source families used by each answer. A query using two families increments both, so source shares can sum to more than 100%. Keywords are normalized lexical terms counted at most once per query. Raw query text is used only inside aggregation and is never returned by this endpoint.

Errors

Status	Meaning
401	Missing or invalid API key, or a required verified principal is absent.
403	The verified principal is not an administrator or operator.
422	keyword_limit is outside 1–50 or is not an integer.