Usage units
What counts as a search unit, ingest unit, AI unit, connector sync, and storage unit — with examples and emission rules.
AACsearch meters six distinct things. Five of them roll up into your plan quota (search units, indexed documents, connector syncs, storage, seats). The sixth — AI usage — runs on a separate pre-paid wallet. Mixing the two is what trips most customers up the first time; this page is the unit-by-unit reference.
Search units
A search unit is the headline meter on the plan. One search unit equals one search request OR one document write.
| Action | Units | Emitted as |
|---|---|---|
POST /search (any filter, sort, pagination) | 1 | SearchUsageEvent { type: "search" } |
POST /multi-search with N queries | N | One SearchUsageEvent per query |
PUT /indexes/{id}/documents (single upsert) | 1 | SearchUsageEvent { type: "ingest" } |
POST /indexes/{id}/documents:batch with N docs | N | One SearchUsageEvent per successful line |
DELETE /indexes/{id}/documents/{external_id} | 1 | SearchUsageEvent { type: "ingest_delete" } |
DELETE …documents:byFilter matching M docs | M | One per matched document |
POST /indexes/{id}/sync (full reindex) | M | One per document re-emitted into the new versioned index |
| Suggest / autocomplete | 1 | SearchUsageEvent { type: "suggest" } |
Aggregation-only query (per_page: 0) | 1 | Counted as a search |
A search that returns zero hits still consumes a unit. A failed search (bad query, 4xx) does not consume a unit. A 429 or 5xx response also does not consume a unit.
Why "search OR ingest"?
The two have similar load profiles on Typesense and on our infrastructure budget. A single unit makes plan limits easy to reason about, lets you trade ingest for query without thinking about it, and avoids the trap of "I burned my search quota because we did a big reindex" — both are visible in the same place.
Indexed documents (storage quota)
Separately from per-action units, your plan caps the steady-state document count across all your indexes. This is checked at ingest time, not per request.
| Plan | Indexed documents cap |
|---|---|
| Free | 1,000 |
| Starter | 10,000 |
| Pro | 100,000 |
| Business | 1,000,000 |
| Enterprise | Custom |
If the cap is reached, new upserts return quota_exceeded. Reads continue. To free space, delete documents (which decrements the count) or upgrade.
Document size matters: a document is counted as one regardless of field count or length, but very large documents (>1 MB per doc) may hit per-document size limits in the search engine. Aim for documents under 64 KB.
AI units (wallet, separate from plan)
AI usage is not part of search units. It is metered against a separate pre-paid wallet in wallet-ledger.ts, denominated in micro-USD or kopecks.
| Action | Roughly costs (varies by model) | Emitted as |
|---|---|---|
| Knowledge query (RAG with retrieval) | Embedding tokens + LLM tokens | WalletLedgerEntry { type: "knowledge" } |
Embedding generation (/embeddings) | Embedding tokens × model rate | WalletLedgerEntry { type: "embedding" } |
| AI rerank (on a search request) | Embedding tokens × rerank model rate | WalletLedgerEntry { type: "rerank" } |
| Document summarization | LLM tokens × summarization model rate | WalletLedgerEntry { type: "summarize" } |
| AI chat (conversation history) | Cumulative LLM tokens per turn | WalletLedgerEntry { type: "chat" } |
Each AI call writes a wallet ledger entry with the exact amount drawn down (BigInt micro-USD). If the wallet is empty or below the spending threshold, the call fails with wallet_balance_insufficient and the search/ingest is not affected.
See Wallet & AI credits for top-ups, auto-recharge, and spending limits.
Connector syncs
A connector sync is one full or delta synchronization run by a connector token (ss_connector_*). It is metered per run, not per document inside the run.
| Run type | Units |
|---|---|
Heartbeat (POST /heartbeat) | 0 — heartbeats are free |
| Delta sync (incremental) | 1 sync unit + N search units (one per document) |
| Full sync (reindex) | 1 sync unit + N search units (one per re-emitted doc) |
Your plan caps total syncs per month (300 / 3,000 / 30,000 across paid tiers). For frequent connectors (e.g. five-minute polling from PrestaShop) the cap can become the binding constraint before search-unit volume.
Seats
A seat is a member with any role (owner, admin, member, viewer). Plan caps:
| Plan | Seats |
|---|---|
| Free | 3 |
| Starter | 10 |
| Pro | 25 |
| Business | 100 |
| Enterprise | Custom |
Removed members free their seat immediately. Pending invites do not consume seats — they count only after acceptance.
See Members & Roles for the role model and bulk-invite flow.
Analytics retention
The period selector in Analytics is gated by plan:
| Plan | 24h | 7d | 30d | 90d | 365d |
|---|---|---|---|---|---|
| Free | ✓ | ✓ | — | — | — |
| Starter | ✓ | ✓ | ✓ | — | — |
| Pro | ✓ | ✓ | ✓ | ✓ | — |
| Business | ✓ | ✓ | ✓ | ✓ | ✓ |
| Enterprise | ✓ | ✓ | ✓ | ✓ | ✓ |
Retention is on raw events. Aggregated dashboards (top queries, KPI tiles) are computed on read and not subject to a separate retention window.
Worked examples
Small e-commerce shop
- 5,000 SKUs in one index → 5,000 indexed documents (Starter cap is 10,000 — fits).
- 30,000 visitors / month doing 4 searches each → 120,000 search units / month (over Starter cap of 100,000 — bump to Pro).
- Daily inventory sync = 30 syncs/month (well under any cap).
- No AI features → wallet untouched.
Plan: Pro. Wallet: zero.
Knowledge base with AI Q&A
- 2,000 articles indexed.
- 50,000 search requests / month (well under Pro's 1M cap).
- 5,000 Knowledge queries / month, average 1,500 tokens per query → ~7.5M tokens.
- At a rough embedding+LLM blended rate of $0.005 per 1k tokens → $37.50 / month wallet draw.
Plan: Pro. Wallet: $40 top-up monthly, auto-recharge at $5 threshold.
Marketplace
- 8 tenants, scoped tokens for isolation.
- 80,000 documents across one shared index.
- 2,000,000 searches / month.
Plan: Pro (scoped tokens unlock here). Wallet: zero unless AI rerank is enabled.
Where to find the raw event log
/[orgSlug]/overview— KPI tile shows aggregated units./[orgSlug]/analytics— per-day chart of search and ingest events./admin/wallet(admin only) — raw wallet ledger entries.- v1 REST
GET /api/v1/usage/events— programmatic export, paginated.
Related
- Plans — plan matrix and right-sizing examples.
- Quotas — soft/hard cap behavior and reset schedule.
- Wallet & AI credits — pay-as-you-go AI billing.
- Plans & Limits (architecture) — entitlements code paths.