Billing & Usage

FoxNose meters usage on five independent axes: retrieval units, write units, data storage, vector storage and file units. Each plan includes a monthly allowance on every axis, and no axis uses another's allowance. Plan prices, allowances, limits and overage rates are on the Pricing page.


Metering axes

AxisMeasured inWhat counts
Retrieval unitscountEach billable Flux API read and each read-tool MCP tools/call.
Write unitsweighted countEach record or revision written with content, weighted by embedded tokens. See Weighted writes.
Data storageGBAverage size of your resources and content over the window.
Vector storageGBAverage size of stored embeddings over the window.
File unitsunitsProcessing files in Files. See File units.

Retrieval units. One per request, however many results it returns. The Flux API counts GET resource reads, _search, _schema and _router. MCP counts tools/call of a read tool; initialize, tools/list and ping are free.

Write units. Creating or updating a record or revision with content counts, whether through the Management API, the MCP write tools or their REST twins. Publishing or validating an existing revision is free. A write is never also counted as a retrieval.

Storage. Both storage axes are sampled about every 4 hours and billed on the average across the window, so short spikes barely count.

What is free

Only 2xx and 3xx responses count. 4xx, 5xx, 429 and OPTIONS are always free. File units follow the processing of a file rather than a request: see below.


Weighted writes

A write costs write units in proportion to the text it embeds:

write units = max(1, ceil(embedded_tokens / 500))

Content up to about 500 embedded tokens costs 1 write unit; a resource with 1,500 embedded tokens costs 3.


File units

EventFile units
A page of a document, or an image1
A page analysed for tables (see the tables policy)2 more
A verdict on a file1
A file the malware scan blocks1

Nothing else costs file units: not moderation, the safe copy or page images. Storing, searching and reading file records use the other axes.

  • Without table analysis, a 10-page PDF costs 11 units (10 pages and a verdict) and a photo costs 2.
  • A file refused before it is read, such as unsupported_format or too_large, costs nothing. A blocked or rejected file that reached a verdict pays for it.
  • A re-analysis is billed again.
  • A storage_only file costs units only if the malware scan blocks it.

Only upload grants (hosted upload links included) and re-analyses are checked against the allowance, and each reserves one unit. Work already admitted is never stopped, so a large document admitted near the limit can take usage past it.


Overage and spend cap

On a paid plan, usage beyond an allowance keeps working and is billed after the window at flat per-unit rates. A small overage invoice is waived. The Free plan has no overage: an exhausted axis stops.

A paid organization's spend cap is the most overage it can spend in a window:

  • A default cap is set with the plan. You change it in the dashboard; for a higher cap than the dashboard allows, contact sales@foxnose.net.
  • A cap of zero is a hard stop at the plan allowance.
  • Overage on every axis, file units included, counts toward the one cap.

Reaching a limit

LimitResponse
Spend cap reached (paid)402 spend_cap_reached on billable reads and writes. If storage alone filled the cap, reads keep working and only writes are refused.
Allowance exhausted (Free)402 plan_exhausted naming the axis. Reads stop when retrieval units run out; writes stop when write units or either storage allowance run out.
File units, either caseUpload grants and re-analyses get 402 files_quota_exceeded with the reason spend_cap_reached or plan_exhausted.
File allowance unreadable503 files_quota_unavailable. Nothing was admitted or billed; retry.
Structural limit (projects, collections, keys and so on)403 plan_limit_exceeded with the entity and its limit.

plan_exhausted and files_quota_exceeded name the axis: retrievals, writes, data_storage, vector_storage or file_units. The bodies are in Flux API errors, Management API errors and Create Upload Grant.

Over MCP, a blocked tools/call returns JSON-RPC error -32003 with the same data. The handshake is never blocked, so an agent can still connect and see why.

Structural limits, safety ceilings and rate limits are listed in Management API limits and Flux API limits.


Reading usage

The dashboard shows usage on every axis under Usage trends. Over the API, GET /organizations/{org_key}/usage/ returns the current window, including a file_processing block, and Get File Processing Usage splits file units by kind.


Usage windows

  • Windows are monthly, anchored to the day you subscribed or, on Free, registered.
  • Unused allowance does not roll over.

Subscription lifecycle

Payments are handled by Lemon Squeezy, monthly or annually. Upgrades, downgrades, cancellation and resumption are self-serve in the dashboard.

  • Payment fails: 14 days of full service while the payment is retried, then the organization moves to Free.
  • Downgrade: nothing is deleted. Only creating resources beyond the new plan's limits is blocked.
  • Cancellation: the plan stays active to the end of the paid period, then moves to Free. Your data is kept for at least 90 days.

Was this page helpful?