AACSearch
API-Referenz

Analytics

Übersicht, CSV-Export, langsame Abfragen, Trends, Null-Ergebnis-Alerts, verwandte Anfragen, Experimente und letzte Suchen — alles aus dem 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=preise
GET  /api/v1/analytics/experiments?days=30&index=documentation
GET  /api/v1/recent?limit=8
POST /api/v1/recent

Alle Analytics-Endpunkte sind auf die Organisation des API-Schlüssels begrenzt. Für /analytics/* gilt stats oder search:read (Übersicht) bzw. search:read (übrige); /recent akzeptiert jeden gültigen Schlüssel.

Übersicht

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": "preise", "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 wird auf 7–90 begrenzt. Latenz-Perzentile und die Zahl eindeutiger Anfragen stammen aus dem rohen Query-Log, die Tagesreihe aus der voraggregierten Tabelle.

CSV-Export

curl -sS "$AAC_API/analytics/overview.csv?days=7" \
  -H "Authorization: Bearer $AAC_KEY" \
  -o analytics.csv
date,searches,zero_results,clicks,conversions
2026-10-17,610,49,77,2
2026-10-18,655,52,80,4

Antwort mit text/csv; charset=utf-8 und content-disposition: attachment; filename="aacsearch-analytics-7d.csv". days wird auf 7–90 begrenzt.

Langsame Abfragen

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 preisvergleich",
			"latency_ms": 412,
			"results": 0,
			"index_id": "idx_01HZX8",
			"at": "2026-10-22T14:02:51.000Z"
		}
	],
	"request_id": "req_5c7a9f1b3d5e7a9c1b3d5f7a"
}

days wird auf 1–90, threshold auf 1–10.000 Millisekunden begrenzt; es kommen höchstens 25 Zeilen zurück, die langsamsten zuerst. Abfragen oberhalb der Schwelle deuten meist auf ein breites filter_by, ein großes per_page oder ein ausgeschöpftes num_typos hin.

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 wird auf 1–168 begrenzt, Null-Ergebnis-Abfragen sind ausgeschlossen, die Liste umfasst höchstens 10 Einträge. Gut für einen Block „gerade gesucht“.

Null-Ergebnis-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"
}

Verglichen werden die letzten 24 Stunden mit der Baseline der vorherigen 7 Tage. Ein Index wird gemeldet, wenn er mindestens 20 Suchen hatte, die Null-Ergebnis-Rate mindestens 10 % beträgt und sie entweder 25 % überschreitet oder auf das 1,5-Fache der Baseline gestiegen ist. severity ist high ab 50 % Null-Ergebnis-Rate, sonst medium.

Verwandte Anfragen

curl -sS -G "$AAC_API/analytics/related" \
  -H "Authorization: Bearer $AAC_KEY" \
  --data-urlencode "q=preise"
{
	"q": "preise",
	"queries": [
		{ "query": "preise tarife", "searches": 64 },
		{ "query": "enterprise preise", "searches": 38 }
	],
	"request_id": "req_1f3d5b7a9c1e3f5a7b9d1c3f"
}

Basiert auf Ko-Okkurrenz im Log des Mandanten über 90 Tage, maximal 8 Vorschläge, 60 Sekunden gecacht. Anfragen unter zwei Zeichen liefern eine leere Liste.

Experimente

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"
}

Gruppiert werden nur Abfragen, die mit einem Profil liefen; die Buckets spiegeln also den tatsächlich bedienten Traffic. days wird auf 1–90 begrenzt; ohne index wird organisationsweit aggregiert. Wie die Buckets zugeteilt werden, steht unter A/B-Experimente.

Letzte Suchen

Das Widget führt eine Liste der letzten Anfragen pro Besucher, verschlüsselt über eine anonyme Client-ID, die der Aufrufer liefert. Serverseitige Sessions gibt es nicht.

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":"preise"}'
{
	"ok": true,
	"query": "preise",
	"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": "preise", "at": "2026-10-23T10:41:02.000Z" },
		{ "query": "webhooks", "at": "2026-10-23T10:38:17.000Z" }
	],
	"request_id": "req_8a0c2e4b6d8f0a2c4e6b8d0f"
}

x-aac-client-id muss mindestens 6 Zeichen haben: fehlt er beim Schreiben, folgt 422 CLIENT_ID_REQUIRED, eine Anfrage unter 2 Zeichen ergibt 422 QUERY_TOO_SHORT. Pro Client werden die 20 letzten Einträge gehalten, Wiederholungen dedupliziert. Ein GET ohne Client-ID liefert ein leeres Array statt eines Fehlers — das hält den ersten Render des Widgets einfach. limit wird auf 1–20 begrenzt.

Dokumente

Ingest, Update, Löschen und Export von Dokumenten — POST /documents, Massen-Update, TTL, idempotente Wiederholungen und NDJSON-Export.

Embed-Session

POST /api/v1/embed/session — tauscht einen API-Schlüssel serverseitig gegen ein kurzlebiges, reines Such-Session-Token, das sicher auf einer Seite stehen darf. Dazu die browserseitigen /embed/*-Endpunkte, die es akzeptieren.

On this page

ÜbersichtCSV-ExportLangsame AbfragenTrendsNull-Ergebnis-AlertsVerwandte AnfragenExperimenteLetzte Suchen