Knowledge Bases: Pricing and Billing
Knowledge bases are billed on three meters, on top of your normal model usage. Every organization — with or without a plan — first uses the free trial and then pays as it goes: from its wallet (prepaid) or on its invoice (postpaid). This page explains the units, what is free, how the trial and pay-as-you-go fit together, and how the limits you already know — balance, credit, spending cap — apply.
The prices are on the portal's Knowledge bases → Pricing page (every 402 response links to it in details.price_card_url) and in GET /v1/knowledge_module → prices: the storage and query prices in force (price_per_gb_month, price_per_1k_queries, decimal strings), the tariff version (price_version, effective_from) and the next scheduled version (upcoming). The storage and query prices are the platform tariff, the same for every organization: a plan does not set its own knowledge-base prices. The block is omitted when prices cannot be read at that moment.
Prices are versioned and never retroactive: a query or a processing job is billed at the price in force when it was admitted, and storage at the price in force for each stretch of time it is kept — a new storage price applies from its effective_from onward, never to earlier time.
The three meters
| Meter | Unit | Measured on |
|---|---|---|
| Storage | GB-month | Original bytes of ready documents, over time |
| Queries | per 1,000 queries | Successful retrievals — searches and grounded chat |
| Processing | tokens, at the embedding model's price | Embedding tokens of each new or replaced document |
A grounded chat answer additionally uses the chat model's input and output tokens, billed exactly like any chat request. The source text placed in the prompt counts as input tokens.
What is free
- Creating knowledge bases (they count towards the knowledge-base limit).
- Exports and downloads.
- Search-time embedding, keyword indexing, reranking and index replicas — they are part of the query price.
- Failed processing and every platform retry. Platform-initiated reprocessing (for example a model upgrade) is never charged.
- The temporary second copy while a document is being replaced.
- Refused or failed searches.
- Crawling website sources: previews, discovery and page fetches, and re-fetching pages that did not change.
Storage
- 1 GB = 1,000,000,000 bytes (decimal).
- Measured on the original file size of ready documents — not on chunks, vectors, overlap or replicas. Failed uploads and frozen free-trial data are not billed.
- Measured continuously (byte-seconds, recorded hourly), from the moment a document becomes ready until its deletion is accepted.
- The GB-month uses a fixed 30-day month: 1 GB kept for 30 days = 1 GB-month, and 1 GB kept for a 31-day month = 31/30 ≈ 1.033 GB-month.
- Only storage beyond what the free trial covers is billed:
max(stored − trial storage, 0) × time. The trial's storage is the trial allowance while the trial is enabled for you, otherwise 0 (GET /v1/knowledge_usage→storage.trial_bytes).
Example: 50 MB covered by the trial, 1.05 GB stored for 15 days → 1 GB × 15 days = 0.5 GB-month billable.
The trial's storage is a concurrent capacity (how much you may keep at once), not a monthly amount that accumulates.
Queries
- One successful retrieval = one query — a
POST …/search, or one chat request withknowledge_base_ids— including one that finds nothing. - A chat request over up to 5 knowledge bases is still one query.
- A retried request with the same
Idempotency-Keyis not charged again. - Priced per 1,000 queries.
Example: 500 trial queries per period; 2,500 queries in the period → 2,000 pay-as-you-go queries = 2 × the price per 1,000.
If a retrieval succeeded but the chat model then failed or was refused, the query stays charged; the model part follows the normal inference rules.
Processing
- The actual embedding input tokens of each document version that becomes ready, charged once, at the price of the knowledge base's embedding model for your organization: a price agreed for your organization if there is one, otherwise the model's list price. Plan model prices and plan token allowances do not apply to processing.
- Each offered model has its own processing price. The portal's Create a knowledge base dialog shows it per 1M tokens next to each model, and
GET /v1/knowledge_embedding_modelsreturns it asprocessing_price_per_1m_tokens(decimal string) with itscurrency— the price your organization is charged, not a generic list price. A model with no processing price for your organization cannot be chosen for a new knowledge base (422 validation_failed,details.reason: unpriced). - Replacing a file processes — and bills — the new file.
- Cancelling processing bills only the tokens already embedded; work that had not started is free.
- The upload screen shows an estimate. To cap the cost of one upload request, send
max_processing_cost(USD); a document that would exceed the remaining cap fails withprocessing_budget_exceededinstead of being processed.
Website sources
Website sources add no new meter and no crawl fee. The pages they index are billed exactly like uploaded documents:
| What happens | Charged |
|---|---|
Preview, discovery, robots.txt, sitemaps, llms.txt, page fetches | Nothing |
| A new page, or a page whose text changed | Processing tokens for the new version, and storage for the page's original bytes (the fetched HTML, the rendered HTML when the page was rendered with JavaScript, or the linked PDF, DOCX, … file) |
A page that did not change (the site answers 304 Not Modified, the extracted text is identical, or a scheduled refresh skips it because its sitemap lastmod did not move) | Nothing: no new version, no processing, no extra storage |
| Domain verification and its re-checks, scheduled refreshes themselves | Nothing (a scheduled refresh bills only its new and changed pages) |
| A page that is removed, a page document you delete, a deleted source | Storage stops when the deletion is accepted |
| Platform retries | Nothing |
Free-trial allowances cover pages like any document. When processing cannot be paid (the trial is used up and there is no balance or credit), pages wait in awaiting_budget and the run waits with them; after 24 hours the run fails with budget_exhausted. With a payment problem (payment_suspended) the run fails at once with billing_blocked: the refused page is not charged, and pages accepted before the refusal are processed and billed normally.
Limits are counts, not prices: each source holds at most 100 pages on an unverified domain (5,000 on a verified one), and website pages do not count toward the 1,000 documents per knowledge base, which apply to uploaded files only. Your effective values are in GET /v1/knowledge_module → web.limits. A page cap never deletes pages: a source that is above a lowered cap keeps its pages but gains no new ones.
Free trial
Every organization gets a free trial allowance, with or without a balance, whatever its plan — unless your platform operator has switched the trial off for the platform or for your organization (GET /v1/knowledge_module → trial.enabled_for_tenant is then false). Trial usage is priced at zero and appears as its own zero-amount invoice lines. Default values (your platform operator can change them; read yours from GET /v1/knowledge_module → trial):
| Allowance | Default | Period |
|---|---|---|
| Knowledge bases | 1 | at a time |
| Storage | 50 MB (50,000,000 bytes) | at a time |
| Queries | 500 | per billing period |
| Processing tokens | 1,000,000 | lifetime of the organization |
| Idle period | 30 days | then the knowledge base is frozen |
When a trial allowance is used up, pay-as-you-go takes over automatically: from your wallet if your organization is prepaid, on your invoice if it is postpaid. When your organization cannot pay as it goes — prepaid with no positive balance — requests are refused with 402 trial_exhausted and details.meter naming the allowance (knowledge_bases, storage_bytes, queries, processing_tokens). Creating knowledge bases stays free: once you can pay as you go, the platform's knowledge-base limit applies instead of the trial's count.
A trial knowledge base with no search or upload for the idle period is frozen while your organization cannot pay as it goes (prepaid with no positive balance, or stopped by a payment problem), and deleted after the deletion period (14 days by default; the date that applies is trial.deletion_at) — see Idle free-trial data. Frozen data is not billed.
Trial, then pay-as-you-go
The only order is: free trial first, then pay-as-you-go. It is the same for every organization — pay-as-you-go accounts, organizations on a token or budget plan, and organizations with a commitment contract alike.
- Free trial (zero price), up to each trial allowance.
- Pay-as-you-go at the platform tariff (storage, queries) and the price of the knowledge base's embedding model (processing): held on and paid from your wallet if you are prepaid, accrued on your invoice within your credit limit if you are postpaid.
Each unit is covered once, never counted twice. A plan's included tokens, token quota or USD budget and a commitment contract never cover knowledge-base storage, queries or processing; they keep covering ordinary model usage as before. The chat-model tokens of a grounded chat answer are such ordinary model usage, so your plan or commitment covers them like any other chat request.
There is no knowledge-base-specific ceiling and no overage switch. What limits pay-as-you-go is what limits all your paid usage: the prepaid balance, the postpaid credit limit and the organization spending cap.
Trial usage needs no balance: a prepaid organization with zero balance can still use the trial. Anything beyond the trial needs a positive balance (prepaid) or available credit (postpaid) — also for an organization on a plan.
Warnings are sent at 80 % and 100 % of the trial allowances.
Balance, credit and spending cap
Knowledge work is admitted like any other paid request:
- Prepaid: the estimated pay-as-you-go part is held on your wallet before the work starts and settled with the actual amount afterwards. Without enough balance the request is refused with
402 insufficient_credits(uploads wait inawaiting_budgetfor up to 24 hours instead). Storage is held hour by hour. - Postpaid: usage accrues within your credit limit (
402 credit_limit_exceededbeyond it).
Spend cap
Reserved and charged knowledge-base amounts (all storage, queries and processing beyond the free trial) count toward the organization spending cap. When knowledge-base usage brings the organization to the cap, all paid traffic is refused with 402 payg_spend_cap_exceeded — including ordinary LLM requests, not only knowledge work. Size the cap for both, or raise it when you start storing documents.
Reaching the cap only refuses new paid work until it is raised or the period ends. It does not start the payment-problem deletion schedule.
Knowledge bases switched off on the platform
When your platform operator switches knowledge bases off, an organization that still has knowledge bases keeps them read and export only. Billing does not change: stored documents keep being billed per GB-month until you delete them, and search and grounded chat are billed as usual. Exports and downloads stay free, so you can take your data out and then delete it.
Payment problems
If paid knowledge work is stopped because of an unresolved payment problem, the retention schedule starts: download, export and delete stay open, data is deleted on day 14 unless the problem is resolved first, and no new pay-as-you-go storage charges accrue from that moment. Earlier charges remain due.
On your invoice
Knowledge usage appears on its own lines, separate from model usage:
- Knowledge storage (GB-month), Knowledge queries, Document processing (tokens, per embedding model).
- Separate lines for the free trial and for pay-as-you-go — trial usage appears as zero-amount lines so you can see what the trial absorbed, pay-as-you-go usage on lines labelled pay-as-you-go.
- Knowledge-base amounts are never offset against a plan budget or counted toward a commitment; every amount is payable exactly once, on its knowledge line.
- Prepaid amounts already taken from the wallet are shown as paid.
- A storage line shows its quantity in GB-months with 6 decimal places. When that rounded figure is more than 0.5 % away from the exact quantity (typically a very small amount of storage), the line's description ends with the exact value, for example
, exact 0.000000533298 GB-month.
Knowledge-base usage is counted in your organization's billing period, the same period as the rest of your bill: GET /v1/knowledge_usage → queries.period_start / period_end (UTC timestamps). Period boundaries are always computed in UTC; no time zone of your profile or browser changes them.
Reading your usage with the API
GET /v1/knowledge_usage returns your counters (storage, queries, processing tokens, trial, retention state). Invoices and payment history are on the billing pages and endpoints.
- Queries:
queries.usedis every query of the period:trial.queries_used(covered by the free trial) plusqueries.paid_used(billed pay-as-you-go). A query counts once it is admitted; a query that is released again (for example because it failed) gives its unit back. - Money: a
moneyblock with the period's knowledge-base amounts (decimal strings) is returned only to organization admins and owners signed in to the portal. Members get nomoneyblock, and no API key gets one, whatever its type or scopes. The block is also left out when billing cannot answer at that moment. For billing figures in an integration, use the billing endpoints with a management key.
money field | Meaning |
|---|---|
reserved_amount | Held right now for knowledge work in progress; settled or released when it finishes |
settled_amount | Pay-as-you-go charges booked this period |
collected_amount | Prepaid: the part of settled_amount already paid from your wallet |
unfunded_amount | Prepaid: the part not drawn from your wallet (a shortfall, or storage still waiting for its hourly draw). It is never invoiced |
due_on_invoice | Postpaid: the part no statement has claimed yet, so your next statement asks for it |
invoiced_amount | Postpaid: the part on the period's closing statement |
net_due, paid_from_wallet | The older summary figures, kept for existing readers |
currency, period_id | The currency and the billing period of these amounts |
collected_amount + unfunded_amount + due_on_invoice + invoiced_amount = settled_amount, exactly. Treat a split field that is missing as not reported, never as zero.
In the portal
- Knowledge bases → Usage is the one overview of knowledge usage. The Queries card shows the period's total and the two counters that add up to it: Free trial queries and Billed queries (with the query price). Choose a knowledge base there to see its own query series, latency and feedback. Admins and owners also see Charges: Reserved and Settled this period, split into Paid from wallet, Not yet funded, On your next statement and On a statement (the four
moneysplit fields above). Members see "Only admins and owners can see knowledge charges." instead. - Billing (admins and owners) has a Knowledge line in What you are using: Settled this period and the billed queries, the same figures as Knowledge bases → Usage, with a link to it.
- Dashboard has a Knowledge queries tile with this period's queries. Admins and owners see what knowledge cost this period under it; members see their knowledge base count.
- The Try search card says what one search uses before you press Search: the trial queries left, or the query price once the trial is used up.
Errors you may see
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 402 | trial_exhausted | A trial allowance (details.meter) is used up and your organization cannot pay as it goes (prepaid with no positive balance) | Add funds; for queries you can also wait for the next period |
| 402 | insufficient_credits | Prepaid balance cannot cover the hold | Add balance |
| 402 | credit_limit_exceeded | Postpaid credit limit reached | Settle or ask for a higher limit |
| 402 | payg_spend_cap_exceeded | Organization spending cap reached | Raise the organization cap (Billing page) or wait for the next period |
| 402 | payment_suspended | Paid work stopped because of a payment problem | Resolve the payment; download and delete stay open |
| 409 | resource_limit_reached | Knowledge-base, uploaded-document or website-source count limit (details.limit_name) | Delete something; the limits are platform settings, the same for every organization (plans do not change them) |
| 409 | trial_kb_frozen | Idle trial knowledge base frozen | Add funds (and resolve any payment problem) to unfreeze it, or export/delete before details.deletion_at |
| 409 | kb_suspended | Knowledge base suspended because of a payment problem (details.reason: payment_suspended) | Resolve the payment |
| 413 | file_too_large, too_many_files, request_too_large | Size limits | Split the upload |
| 422 | metadata_*, filter_invalid, query_too_long, file-type codes | Invalid input | Fix the request |
| 429 | rate_limited, concurrency_limited | Temporary rate or concurrency limit | Retry after Retry-After; nothing is charged |
| 503 | billing_unavailable | Billing could not be reached; uploads, replacements and retries are refused rather than run unbilled. By default searches and grounded chat are served anyway; their query charge is settled once billing answers again | Retry after Retry-After |
| 503 | maintenance_mode, knowledge_unavailable, retrieval_unavailable | Temporary unavailability | Retry after Retry-After |
Every 402 carries details.price_card_url, details.meter and, when known, limit, used and resets_at. The complete list with retry advice is in Error Codes.