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
| Axis | Measured in | What counts |
|---|---|---|
| Retrieval units | count | Each billable Flux API read and each read-tool MCP tools/call. |
| Write units | weighted count | Each record or revision written with content, weighted by embedded tokens. See Weighted writes. |
| Data storage | GB | Average size of your resources and content over the window. |
| Vector storage | GB | Average size of stored embeddings over the window. |
| File units | units | Processing 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
| Event | File units |
|---|---|
| A page of a document, or an image | 1 |
A page analysed for tables (see the tables policy) | 2 more |
| A verdict on a file | 1 |
| A file the malware scan blocks | 1 |
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_formatortoo_large, costs nothing. A blocked or rejected file that reached a verdict pays for it. - A re-analysis is billed again.
- A
storage_onlyfile 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
| Limit | Response |
|---|---|
| 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 case | Upload grants and re-analyses get 402 files_quota_exceeded with the reason spend_cap_reached or plan_exhausted. |
| File allowance unreadable | 503 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.
FoxNose never deletes data because of a downgrade or cancellation.
Related
- Pricing — plan prices, allowances, limits and overage rates.
- Management API limits and Flux API limits — structural limits, safety ceilings and rate limits.
- Flux API errors and Management API errors — status codes and error bodies.
- Files — how file processing works.