Skip to main content

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​

MeterUnitMeasured on
StorageGB-monthOriginal bytes of ready documents, over time
Queriesper 1,000 queriesSuccessful retrievals — searches and grounded chat
Processingtokens, at the embedding model's priceEmbedding 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 with knowledge_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-Key is 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_models returns it as processing_price_per_1m_tokens (decimal string) with its currency — 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 with processing_budget_exceeded instead 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 happensCharged
Preview, discovery, robots.txt, sitemaps, llms.txt, page fetchesNothing
A new page, or a page whose text changedProcessing 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 themselvesNothing (a scheduled refresh bills only its new and changed pages)
A page that is removed, a page document you delete, a deleted sourceStorage stops when the deletion is accepted
Platform retriesNothing

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):

AllowanceDefaultPeriod
Knowledge bases1at a time
Storage50 MB (50,000,000 bytes)at a time
Queries500per billing period
Processing tokens1,000,000lifetime of the organization
Idle period30 daysthen 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.

  1. Free trial (zero price), up to each trial allowance.
  2. 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 in awaiting_budget for up to 24 hours instead). Storage is held hour by hour.
  • Postpaid: usage accrues within your credit limit (402 credit_limit_exceeded beyond it).

Spend cap​

Knowledge-base spend counts toward your organization spending 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.used is every query of the period: trial.queries_used (covered by the free trial) plus queries.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 money block with the period's knowledge-base amounts (decimal strings) is returned only to organization admins and owners signed in to the portal. Members get no money block, 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 fieldMeaning
reserved_amountHeld right now for knowledge work in progress; settled or released when it finishes
settled_amountPay-as-you-go charges booked this period
collected_amountPrepaid: the part of settled_amount already paid from your wallet
unfunded_amountPrepaid: the part not drawn from your wallet (a shortfall, or storage still waiting for its hourly draw). It is never invoiced
due_on_invoicePostpaid: the part no statement has claimed yet, so your next statement asks for it
invoiced_amountPostpaid: the part on the period's closing statement
net_due, paid_from_walletThe older summary figures, kept for existing readers
currency, period_idThe 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 money split 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​

StatusCodeMeaningWhat to do
402trial_exhaustedA 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
402insufficient_creditsPrepaid balance cannot cover the holdAdd balance
402credit_limit_exceededPostpaid credit limit reachedSettle or ask for a higher limit
402payg_spend_cap_exceededOrganization spending cap reachedRaise the organization cap (Billing page) or wait for the next period
402payment_suspendedPaid work stopped because of a payment problemResolve the payment; download and delete stay open
409resource_limit_reachedKnowledge-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)
409trial_kb_frozenIdle trial knowledge base frozenAdd funds (and resolve any payment problem) to unfreeze it, or export/delete before details.deletion_at
409kb_suspendedKnowledge base suspended because of a payment problem (details.reason: payment_suspended)Resolve the payment
413file_too_large, too_many_files, request_too_largeSize limitsSplit the upload
422metadata_*, filter_invalid, query_too_long, file-type codesInvalid inputFix the request
429rate_limited, concurrency_limitedTemporary rate or concurrency limitRetry after Retry-After; nothing is charged
503billing_unavailableBilling 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 againRetry after Retry-After
503maintenance_mode, knowledge_unavailable, retrieval_unavailableTemporary unavailabilityRetry 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.