AACSearch
Справочник API

Аналитика

Обзор, экспорт в CSV, медленные запросы, тренды, алерты по пустой выдаче, связанные запросы, эксперименты и недавние поиски — всё из журнала запросов.

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=тарифы
GET  /api/v1/analytics/experiments?days=30&index=documentation
GET  /api/v1/recent?limit=8
POST /api/v1/recent

Все эндпоинты аналитики ограничены организацией ключа. Для /analytics/* нужен stats или search:read (для обзора) и search:read для остальных; /recent принимает любой валидный ключ.

Обзор

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": "тарифы", "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 ограничивается диапазоном 7–90. Перцентили задержки и число уникальных запросов берутся из сырого журнала, дневной ряд — из предварительно агрегированной таблицы.

Экспорт в CSV

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

Тип ответа — text/csv; charset=utf-8, заголовок content-disposition: attachment; filename="aacsearch-analytics-7d.csv". days ограничивается диапазоном 7–90.

Медленные запросы

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 ограничивается 1–90, threshold — 1–10 000 миллисекунд; возвращается не более 25 строк, самые медленные сверху. Запросы выше порога обычно означают широкий filter_by, большой per_page или исчерпанный num_typos.

Тренды

curl -sS "$AAC_API/analytics/trending?hours=1" \
  -H "Authorization: Bearer $AAC_KEY"
{
	"hours": 1,
	"queries": [
		{ "query": "вебхуки", "count": 42 },
		{ "query": "лимиты", "count": 31 }
	],
	"request_id": "req_7e9b1d3f5a7c9e1b3d5f7a9c"
}

hours ограничивается 1–168, запросы без результатов исключаются, список — не больше 10 позиций. Подходит для блока «сейчас ищут».

Алерты по пустой выдаче

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

Сравниваются последние 24 часа с базовой линией за предыдущие 7 дней. Индекс попадает в отчёт, если по нему было минимум 20 запросов, доля пустых ответов не меньше 10% и при этом она либо превысила 25%, либо выросла до 1,5× базовой. severity равен high при доле пустых ответов от 50%, иначе medium.

Связанные запросы

curl -sS -G "$AAC_API/analytics/related" \
  -H "Authorization: Bearer $AAC_KEY" \
  --data-urlencode "q=тарифы"
{
	"q": "тарифы",
	"queries": [
		{ "query": "тарифы и планы", "searches": 64 },
		{ "query": "enterprise тарифы", "searches": 38 }
	],
	"request_id": "req_1f3d5b7a9c1e3f5a7b9d1c3f"
}

Строится по совместной встречаемости в журнале тенанта за 90 дней, не более 8 подсказок, кешируется на 60 секунд. Запросы короче двух символов возвращают пустой список.

Эксперименты

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

Группируются только запросы, выполненные с профилем, поэтому корзины отражают реально обслуженный трафик. days ограничивается 1–90; без index данные агрегируются по всей организации. Как назначаются корзины — в разделе A/B-эксперименты.

Недавние поиски

Виджет хранит историю запросов посетителя, ключом служит анонимный client id, который передаёт вызывающая сторона. Серверной сессии нет.

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":"тарифы"}'
{
	"ok": true,
	"query": "тарифы",
	"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": "тарифы", "at": "2026-10-23T10:41:02.000Z" },
		{ "query": "вебхуки", "at": "2026-10-23T10:38:17.000Z" }
	],
	"request_id": "req_8a0c2e4b6d8f0a2c4e6b8d0f"
}

x-aac-client-id должен быть не короче 6 символов: без него запись даёт 422 CLIENT_ID_REQUIRED, а запрос короче 2 символов — 422 QUERY_TOO_SHORT. Хранятся 20 последних записей на клиента, повторы дедуплицируются. GET без client id возвращает пустой массив, а не ошибку — так проще первый рендер виджета. limit ограничивается 1–20.

Документы

Загрузка, обновление, удаление и экспорт документов — POST /documents, массовое обновление, TTL, идемпотентные повторы и экспорт в NDJSON.

Сессия встраивания

POST /api/v1/embed/session — обмен API-ключа на сервере на короткоживущий токен сессии только для поиска, который безопасно класть на страницу. А также браузерные эндпоинты /embed/*, принимающие этот токен.

On this page

ОбзорЭкспорт в CSVМедленные запросыТрендыАлерты по пустой выдачеСвязанные запросыЭкспериментыНедавние поиски