Квоты и биллинг

AACSearch считает деньги в два слоя: месячный тариф с включёнными объёмами и предоплаченный кошелёк, который покрывает превышение. Пока объём не исчерпан, за отдельные запросы не списывается ничего.

Четыре метрики учётаCopy Anchor Link

Не тарифицируются: /suggest (автодополнение не может быть платным за нажатие клавиши), /status, /capabilities, чтение аналитики и трафик консоли.

documents — это измерение, а не счётчик: значение читается из SearchDocument, поэтому удаление документов освобождает объём уже при следующей проверке, а не в конце периода.

Включённые объёмыCopy Anchor Link

Из биллинг-каталога (packages/billing/config.ts):

Цены превышения за блок:

У Free цен превышения нет: лимит — это стена, а не счёт. На Free доступен aiAnswer (RAG) с небольшим жёстко ограниченным объёмом 10 000 AI-токенов; векторного и гибридного поиска, multi-search, curations, grouping, geo, reindex, экспорта, custom-sort и аналитики запросов нет.

Как считается списаниеCopy Anchor Link

1. Период — календарный месяц по UTC (2026-10), сброс в 00:00 UTC первого числа.
2. Счётчики увеличиваются на каждом вызове.
3. Пока used <= limit, вызов ничего не стоит, x-aac-charged-cents равен 0.
4. Сверх лимита списывается каждый начатый блок: 1 001 поиск после границы блока в 1 000 — это два блока, а не 1,001 блока.
5. Если кошелёк не покрывает блок, вызов падает с 402 PAYMENT_REQUIRED.

Поскольку списание поблочное, пакетная загрузка дешевле потоковой: один импорт из 500 документов стоит столько же, сколько один документ.

Как посмотреть состояниеCopy Anchor Link

curl -sS "$AAC_API/billing/usage" -H "Authorization: Bearer $AAC_KEY"

{
	"usage": {
		"plan": "pro",
		"planName": "Pro",
		"period": "2026-10",
		"resetsAt": "2026-11-01T00:00:00.000Z",
		"searches": { "used": 512400, "limit": 500000 },
		"documents": { "used": 51204, "limit": 50000 },
		"aiTokens": { "used": 24800, "limit": 100000 },
		"indexes": { "used": 3, "limit": 10 },
		"apiKeys": { "used": 2, "limit": 10 },
		"connectors": { "used": 1, "limit": 10 },
		"wallet": { "balanceCents": 4200, "currency": "USD" }
	},
	"request_id": "req_2b4d6f8a0c2e4b6d8f0a2c4e"
}

used может превышать limit — это и есть превышение, уже списанное или списываемое. wallet равен null, если у тенанта никогда не было пополнений.

curl -sS "$AAC_API/billing/wallet" -H "Authorization: Bearer $AAC_KEY"

{
	"wallet": { "balanceCents": 4200, "currency": "USD" },
	"plan": "pro",
	"period": "2026-10",
	"resets_at": "2026-11-01T00:00:00.000Z",
	"transactions": [
		{
			"id": "txn_01HZYA",
			"type": "credit",
			"amount_cents": 5000,
			"balance_after_cents": 5000,
			"description": "Top-up credits_50",
			"metric": null,
			"created_at": "2026-10-02T09:12:00.000Z"
		},
		{
			"id": "txn_01HZYB",
			"type": "debit",
			"amount_cents": -800,
			"balance_after_cents": 4200,
			"description": "search overage: 16 blocks",
			"metric": "searches",
			"created_at": "2026-10-21T18:03:11.000Z"
		}
	]
}

amount_cents со знаком: пополнения положительные, списания отрицательные. Эндпоинт кошелька перед ответом сверяет покупки, поэтому пополнение с задержавшимся вебхуком всё равно появится при следующем опросе.

ПополненияCopy Anchor Link

Три предоплаченных пакета: credits_10 ($10), credits_50 ($50), credits_200 ($200). Они покупаются через платёжного провайдера (в этом развёртывании — Stripe Checkout) и попадают в журнал операций: потерянный вебхук задерживает зачисление, но не отменяет его.

Пакеты не истекают, и их нельзя обменять на смену тарифа: они покрывают только превышение.

Что происходит при достижении лимитаCopy Anchor Link

{
	"error": {
		"code": "QUOTA_EXCEEDED",
		"message": "Monthly searches quota exhausted (512400/500000 for 2026-10)",
		"request_id": "req_3c5e7a9b1d3f5a7c9e1b3d5f",
		"details": {
			"metric": "searches",
			"limit": 500000,
			"used": 512400,
			"period": "2026-10",
			"resetsAt": "2026-11-01T00:00:00.000Z"
		}
	}
}

Как обрабатывать правильно: при QUOTA_EXCEEDED прочитайте details.metric и details.resetsAt, прекратите повторы до этого момента и покажите закешированный результат или выдачу только по ключевым словам вместо страницы ошибки. Разница между 429 RATE_LIMITED (секунды) и 429 QUOTA_EXCEEDED (до конца периода) — в error.code, а не в статусе.

Приближение к лимитуCopy Anchor Link

Планировщик раз в несколько минут проверяет использование. Когда searches, documents или ai_tokens пересекает 80 % и затем 100 % включённого объёма, каждый владелец получает письмо и уведомление в приложении (если не отключил его) — один раз на метрику, порог и период. Если первая проверка уже видит 100 %, отправляется только уведомление об исчерпании. documents — это запас, а не месячный поток: уведомление по нему отправляется один раз на порог и снова взводится, только когда число документов опустится ниже этого порога, поэтому заполненный индекс не присылает уведомление каждый месяц.

СчетаCopy Anchor Link

После закрытия месяца ежедневная задача планировщика создаёт по одному счёту на организацию: использованный объём, блоки превышения, списанные с кошелька (по тарифу и цене блока, действовавшим в момент списания каждого блока, даже если тариф с тех пор сменился), блоки, которые кошелёк не смог оплатить, — отдельной неоплаченной строкой, и прочие движения кошелька. Подписку выставляет платёжный провайдер. Счета — в Настройки → Биллинг (с PDF) и в GET /billing/invoices (scope billing:read). Подробнее — Биллинг.

Если платёж не прошёлCopy Anchor Link

Как держать расход разумнымCopy Anchor Link

• Следите за x-aac-quota-remaining в каждом ответе, а не опрашивайте /billing/usage. Алерт на 10% остатка.
• Отключайте неиспользуемое. Семантический поиск на тарифе без hybridSearch падает громко, а голосовые и графические вызовы на Free (10 000 AI-токенов) упрутся в лимит очень быстро.
• Для подсказок используйте suggest. Он бесплатен, а /search на каждое нажатие — нет.
• Загружайте пакетами. Блоки списываются за начатый блок, а не за документ.
• Предпочитайте filter_by, а не per_page. Загрузить 250 строк и фильтровать на клиенте — всё равно один поиск, но лишний трафик и задержка.
• Ретенция — тоже квота. Хранение журнала 7 дней на Free означает, что /analytics/overview?days=30 опирается на меньшую историю, но не на пустоту: предварительно агрегированный ряд сохраняет дневную динамику.

Бюджеты организацииCopy Anchor Link

Раздел «Бюджеты» доступен в кошельке. Владелец организации задаёт месячные лимиты запросов, новых документов, единиц AI-токенов, полных переиндексаций и списаний кошелька в центах. Пустое поле снимает дополнительный лимит; ноль запрещает новое потребление. Лимиты календарного месяца UTC действуют одновременно с ограничениями тарифа.

Панель разделяет использование, резерв и доступный остаток и показывает начало учёта. Учёт бюджета начинается с активации. Денежный расход — фактическое списание: тарифные блоки, оплаченные операцией, относятся к организации, включая ранее неоплаченные блоки. Это не оценка стоимости отдельного запроса. Неиспользованный резерв возвращается при завершении. После аварии процесса неопределённый резерв остаётся зарезервированным: время само по себе не доказывает отсутствие расхода.