Kontingente und Abrechnung

AACSearch rechnet in zwei Schichten: ein monatlicher Tarif mit Inklusivmengen und ein Prepaid-Wallet für Überschreitung. Beide werden pro Abrechnungsperiode (YYYY-MM, Reset am 1. um 00:00 UTC) geführt.

Was gezählt wirdCopy Anchor Link

Nicht gezählt: suggest (jeder Tastendruck würde sonst Geld kosten), stats, Analytics-Leseoperationen, GET /documents/{id}, scoped-key, capabilities, status. Diese Aufrufe unterliegen nur dem Rate-Limit.

documents ist ein Bestand, kein Strom: Löschen senkt die Zahl sofort, und ein Reindex zählt die Dokumente des neuen Index. Deshalb kann ein Import das Kontingent überschreiten, ohne dass ein Zähler „hochläuft" — er liegt einfach über der Grenze.

InklusivmengenCopy Anchor Link

Die Seitenlänge ist eine harte Obergrenze: per_page=500 in Free wird auf 50 gekappt, nicht abgelehnt.

ÜberschreitungCopy Anchor Link

Free hat keine Überschreitungspreise. Beim Erreichen eines Limits kommt 429 QUOTA_EXCEEDED und es wird nichts belastet — ein Free-Mandant kann keine Rechnung erzeugen, die er nicht erwartet hat.

Bei Pro und Enterprise wird jeder angefangene Block aus dem Wallet bezahlt. 16 Blöcke über dem Suche-Limit sind 8,00 $, unabhängig davon, ob der 16. Block nur ein Byte über der Grenze lag.

WalletCopy Anchor Link

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"
		}
	],
	"request_id": "req_4f6a8c0e2b4d6f8a0c2e4b6d"
}

Das Ledger ist append-only: Jede Belastung ist eine Zeile mit balance_after_cents, Sie können den Verlauf also nachrechnen. Aufladungen sind Prepaid-Pakete zu 10, 50 und 200 USD; der Kauf läuft über den Zahlungsanbieter, das Guthaben wird danach als credit verbucht.

Ist das Guthaben bei einer Überschreitung null, scheitert der Aufruf mit 402 PAYMENT_REQUIRED, nicht mit 429. Der Unterschied ist wichtig für Clients: 402 heißt „zahlen oder Tarif wechseln", 429 heißt „später nochmal".

Verbrauch lesenCopy 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": 500000, "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"
}

Dieselbe Struktur steckt in jeder Antwort, die Kontingent verbraucht — POST /documents und POST /search liefern sie unter usage mit, Sie müssen also nicht zusätzlich pollen. wallet ist null, wenn der Mandant nie Guthaben hatte.

Tarifgebundene FunktionenCopy Anchor Link

Free enthält Stichwortsuche, Synonyme, Stopwords, Connectoren, scheduledSync und aiAnswer (RAG) mit einem kleinen, hart begrenzten Kontingent von 10.000 KI-Token. Nicht enthalten: vectorSearch, hybridSearch, curations, grouping, geoSearch, multiSearch, reindex, exportDocuments, customSort, queryAnalytics.

Der Fehler ist je nach Weg unterschiedlich: ein fehlender Scope ergibt 403 FORBIDDEN, eine Tarifgrenze wird von der Metering-Schicht abgelehnt. In beiden Fällen scheitert der Request, statt still ein schlechteres Ergebnis zu liefern — das ist Absicht, damit ein Tarifwechsel keine Verhaltensänderung verbirgt.

Annäherung an ein LimitCopy Anchor Link

Der Scheduler prüft den Verbrauch alle paar Minuten. Überschreitet searches, documents oder ai_tokens 80 % und dann 100 % der Inklusivmenge, erhalten alle Owner eine E-Mail und eine In-App-Benachrichtigung (sofern nicht abgeschaltet) — einmal pro Metrik, Schwelle und Periode, nicht bei jedem Request. Findet schon die erste Prüfung eine Metrik bei 100 %, wird nur der Hinweis „aufgebraucht“ gesendet. documents ist ein Bestand, kein monatlicher Strom: Sein Hinweis kommt einmal pro Schwelle und wird erst wieder scharf geschaltet, wenn die Dokumentzahl unter diese Schwelle fällt — ein voller Index meldet sich also nicht jeden Monat.

RechnungenCopy Anchor Link

Nach Monatsende erzeugt ein täglicher Scheduler-Job eine Rechnung pro Organisation: genutzte Inklusivmenge, aus dem Wallet bezahlte Überschreitungsblöcke (bepreist mit dem Tarif und Blockpreis, die zum Zeitpunkt der jeweiligen Belastung galten, auch wenn sich der Tarif inzwischen geändert hat), Blöcke, die das Wallet nicht decken konnte, als eigene unbezahlte Position, sowie weitere Wallet-Bewegungen. Das Abo rechnet der Zahlungsanbieter ab. Rechnungen stehen unter Einstellungen → Abrechnung (mit PDF) und über GET /billing/invoices (Scope billing:read) bereit. Siehe Abrechnung.

Bei ZahlungsausfallCopy Anchor Link

BetriebsempfehlungenCopy Anchor Link

• Auf 80 % warnen, nicht auf 100 %. searches.used / searches.limit aus /billing/usage ist die Zahl, die in Ihr Monitoring gehört.
• x-aac-quota-remaining mitloggen. Damit sehen Sie den Verbrauch pro Aufruf, ohne zusätzliche Requests.
• Dokumentenbestand vor großen Importen prüfen. documents ist ein Bestand; ein Sitemap-Import von 60.000 Seiten in einen 50.000-Dokumente-Tarif erzeugt sofort Überschreitung.
• reindex-Kontingent für Schemaarbeit reservieren. Ein Lauf pro Schemaänderung; Gewichte und Synonyme brauchen keinen.
• Wallet nicht als Budgetierungswerkzeug behandeln. Es ist eine Überlaufversicherung. Wer regelmäßig überzieht, fährt mit dem nächsthöheren Tarif günstiger.

OrganisationsbudgetsCopy Anchor Link

Budgets sind im Wallet verfügbar. Organisationsinhaber setzen monatliche Limits für Suchanfragen, neue Dokumente, KI-Token-Einheiten, vollständige Neuindizierungen und Wallet-Abbuchungen in Cent. Leer bedeutet unbegrenzt; null sperrt neue Nutzung. UTC-Kalendermonatslimits gelten zusätzlich zu den Tariflimits.

Die Ansicht trennt Verbrauch, Reservierungen und verfügbares Budget und zeigt den Beginn der Erfassung bei Aktivierung. Geldbeträge sind tatsächliche Abbuchungen: ein eingezogener Tarifblock wird der Organisation zugeordnet, auch bei zuvor unbezahlten Blöcken. Ungenutzte Reservierungen werden bei Abschluss freigegeben. Unklare Reservierungen nach einem Prozessabsturz bleiben reserviert; Zeitablauf allein beweist keinen fehlenden Verbrauch.