Analytics
Overview, CSV export, slow queries, trending, zero-result alerts, related queries, experiments and recent searches — all read from the query log.
GET /api/v1/analytics/overview?days=30
GET /api/v1/analytics/overview.csv?days=30
GET /api/v1/analytics/slow-queries?days=7&threshold=200
GET /api/v1/analytics/trending?hours=1
GET /api/v1/analytics/alerts
GET /api/v1/analytics/related?q=pricing
GET /api/v1/analytics/experiments?days=30&index=documentation
GET /api/v1/recent?limit=8
POST /api/v1/recentAll analytics endpoints are scoped to the organization behind the API key. /analytics/* requires stats or search:read for the overview and search:read elsewhere; /recent accepts any valid key.
Overview
curl -sS "$AAC_API/analytics/overview?days=30" \
-H "Authorization: Bearer $AAC_KEY"{
"overview": {
"days": 30,
"totals": {
"searches": 18420,
"uniqueQueries": 4127,
"clicks": 2310,
"zeroResultRate": 0.081,
"ctr": 0.125,
"avgLatencyMs": 19,
"p95LatencyMs": 61,
"aiTokens": 24800,
"conversions": 96,
"conversionValueCents": 189900
},
"series": [
{
"date": "2026-10-22",
"searches": 640,
"zeroResults": 44,
"clicks": 81,
"conversions": 3
},
{
"date": "2026-10-23",
"searches": 702,
"zeroResults": 51,
"clicks": 92,
"conversions": 5
}
],
"topQueries": [{ "query": "pricing", "count": 214 }],
"zeroQueries": [{ "query": "sso saml", "count": 31 }],
"topDocuments": [{ "documentId": "pricing", "clicks": 180 }],
"indexes": [
{
"id": "idx_01HZX8",
"slug": "documentation",
"name": "Documentation",
"documents": 137,
"searches": 9200,
"zeroResultRate": 0.06,
"avgLatencyMs": 17.4
}
],
"plan": {
"id": "pro",
"limits": { "documents": 50000, "searches": 500000, "indexes": 10, "apiKeys": 10 },
"usage": { "searches": 18420, "documents": 137 },
"period": "2026-10",
"resetsAt": "2026-11-01T00:00:00.000Z"
},
"wallet": { "balanceCents": 0, "currency": "USD" }
},
"request_id": "req_2b4d6f8a0c1e3b5d7a9f1c3e"
}days is clamped to 7–90. Latency percentiles and unique-query counts come from the raw query log; the daily series comes from the pre-aggregated rollup.
CSV export
curl -sS "$AAC_API/analytics/overview.csv?days=7" \
-H "Authorization: Bearer $AAC_KEY" \
-o analytics.csvdate,searches,zero_results,clicks,conversions
2026-10-17,610,49,77,2
2026-10-18,655,52,80,4Responds with text/csv; charset=utf-8 and content-disposition: attachment; filename="aacsearch-analytics-7d.csv". days is clamped to 7–90.
Slow queries
curl -sS "$AAC_API/analytics/slow-queries?days=7&threshold=100" \
-H "Authorization: Bearer $AAC_KEY"{
"days": 7,
"threshold_ms": 100,
"queries": [
{
"query": "enterprise sso pricing comparison",
"latency_ms": 412,
"results": 0,
"index_id": "idx_01HZX8",
"at": "2026-10-22T14:02:51.000Z"
}
],
"request_id": "req_5c7a9f1b3d5e7a9c1b3d5f7a"
}days is clamped to 1–90 and threshold to 1–10,000 milliseconds; at most 25 rows are returned, slowest first. Queries above the threshold usually mean a wide filter_by, a large per_page or an exhausted num_typos search.
Trending
curl -sS "$AAC_API/analytics/trending?hours=1" \
-H "Authorization: Bearer $AAC_KEY"{
"hours": 1,
"queries": [
{ "query": "webhooks", "count": 42 },
{ "query": "rate limits", "count": 31 }
],
"request_id": "req_7e9b1d3f5a7c9e1b3d5f7a9c"
}hours is clamped to 1–168, zero-result queries are excluded, and the list is capped at 10 entries. Good for a "popular right now" block.
Zero-result alerts
curl -sS "$AAC_API/analytics/alerts" \
-H "Authorization: Bearer $AAC_KEY"{
"window_hours": 24,
"alerts": [
{
"index": "documentation",
"name": "Documentation",
"searches": 640,
"zero_rate": 0.31,
"baseline_zero_rate": 0.09,
"severity": "medium"
}
],
"request_id": "req_9c1e3b5d7a9f1c3e5b7d9a1f"
}The comparison is the last 24 hours against the preceding 7-day baseline. An index is reported when it had at least 20 searches, its zero-result rate is at least 10%, and it either crossed 25% or rose to 1.5× its baseline. severity is high at a zero-result rate of 50% or more, otherwise medium.
Related queries
curl -sS -G "$AAC_API/analytics/related" \
-H "Authorization: Bearer $AAC_KEY" \
--data-urlencode "q=pricing"{
"q": "pricing",
"queries": [
{ "query": "pricing plans", "searches": 64 },
{ "query": "enterprise pricing", "searches": 38 }
],
"request_id": "req_1f3d5b7a9c1e3f5a7b9d1c3f"
}Derived from co-occurrence in the tenant's log over 90 days, capped at 8 suggestions and cached for 60 seconds. Queries shorter than two characters return an empty list.
Experiments
curl -sS "$AAC_API/analytics/experiments?days=30&index=documentation" \
-H "Authorization: Bearer $AAC_KEY"{
"days": 30,
"index": "documentation",
"buckets": [
{
"profile": "control",
"searches": 8240,
"zero_rate": 0.11,
"avg_latency_ms": 18,
"avg_top_score": 1720.4
},
{
"profile": "weights-v2",
"searches": 8106,
"zero_rate": 0.07,
"avg_latency_ms": 19,
"avg_top_score": 2145.8
}
],
"request_id": "req_3b5d7f9a1c3e5b7d9f1a3c5e"
}Only queries that ran with a profile are grouped, so the two buckets reflect the traffic each profile actually served. days is clamped to 1–90; omit index to aggregate across the organization. How the buckets are assigned is described in A/B experiments.
Recent searches
The widget keeps a per-visitor list of recent queries, keyed by an anonymous client id the caller supplies. There is no server-side session.
curl -sS -X POST "$AAC_API/recent" \
-H "Authorization: Bearer $AAC_KEY" \
-H "Content-Type: application/json" \
-H "x-aac-client-id: 6a1f0c2e-9b7d-4c8a-9e3f-2d1b0a9c8e7f" \
-d '{"query":"pricing"}'{
"ok": true,
"query": "pricing",
"request_id": "req_6d8f0a2c4e6b8d0f2a4c6e8b"
}curl -sS "$AAC_API/recent?limit=8" \
-H "Authorization: Bearer $AAC_KEY" \
-H "x-aac-client-id: 6a1f0c2e-9b7d-4c8a-9e3f-2d1b0a9c8e7f"{
"queries": [
{ "query": "pricing", "at": "2026-10-23T10:41:02.000Z" },
{ "query": "webhooks", "at": "2026-10-23T10:38:17.000Z" }
],
"request_id": "req_8a0c2e4b6d8f0a2c4e6b8d0f"
}x-aac-client-id must be at least 6 characters; missing it on a write is 422 CLIENT_ID_REQUIRED, a query shorter than 2 characters is 422 QUERY_TOO_SHORT. The list keeps the 20 most recent entries per client and de-duplicates repeats. GET without a client id returns an empty array rather than an error, which keeps the widget's first render simple. limit is clamped to 1–20.