Billing & Usage

FoxNose meters usage along four independent axes — retrievals, writes, data storage, and vector storage. Your plan includes a monthly allowance on each axis, and each axis is tracked and billed on its own. This page explains exactly what increments each axis, which responses are free, how weighted writes are calculated, and what happens when you reach a plan allowance or a spend cap.

The four metering axes

Every plan carries a separate monthly allowance for each of the four axes below. Usage on one axis never draws down another.

Retrievals

A retrieval is counted once for each billable read on the Flux API — GET resource reads, _search, _schema (schema introspection), and _router (router introspection) — and once for each read-tool MCP tools/call. Counting is strictly 1:1 with the request: a single search that returns N results counts as one retrieval, not N.

MCP handshake and discovery traffic is free. initialize, tools/list, and ping never increment retrievals. Only tools/call does — and a write-tool call increments Writes instead (below), never both. See Knowledge MCP for the full surface.

Writes

Writes are weighted by the amount of content vectorized on publish, so a large document costs proportionally more than a small one. The formula and reasoning are in Weighted writes below.

Flux-side writes — the MCP write tools (create_record, update_record) and their REST twins (POST / PUT) — run the same publish pipeline and meter identically: one call = one weighted write, reported back as write_units. A write call is never additionally counted as a retrieval.

Data storage and vector storage

Storage is not billed per request. Both storage axes are sampled approximately every 4 hours and billed on the average across the cycle window, so short-lived spikes do not disproportionately affect your bill.

What is billed

Only successful responses are billed. A request is billable only when it returns a 2xx or 3xx status.

The following are never billed:

• 4xx client errors (validation, auth, not found, and so on).
• 5xx server errors.
• 429 rate-limit responses.
• OPTIONS preflight requests.

If a request fails, it costs nothing. You are only charged for work that FoxNose actually completed successfully.

Weighted writes

A write is not a flat per-request charge. It is weighted by the number of embedded tokens in the content being published:

write_count = max(1, ceil(embedded_tokens / 500))

In plain terms: one publish request counts as one write for content up to roughly 500 embedded tokens; larger content is charged proportionally.

For example, a resource whose vectorizable content is about 1,500 embedded tokens counts as 3 write operations (ceil(1500 / 500)).

Embedding large documents is the expensive part of the write path, so write cost is tied to the amount of text embedded rather than to the request count. If a single publish is charged as more than one write operation, this formula is why.

Writes are counted when content is published through the revision pipeline: validate → vectorize → index → publish. Embeddings are generated during the vectorize step, which is where the weighting comes from.

Plans

Each plan sets the monthly allowance on the four metering axes. Annual billing is discounted 17% versus monthly.

Structural limits

Separate from the metering axes, each plan caps the number of structural resources you can create. Exceeding one of these returns 403 plan_limit_exceeded — see Boundaries.

Enterprise plans set these limits per contract. For the full reference, see Management API limits and Flux API limits.

Safety ceilings

There are no plan-based caps on components, schema versions, or schema fields. Reusable schema primitives are never gated — model your content as freely as you need. Collections have a per-plan quota (see the table above).

On top of plan quotas, universal safety ceilings apply to every organization regardless of plan: 5,000 components, 5,000 collections, 1,000 versions per schema, and 1,000 fields per version. These are not commercial limits — they exist so that a runaway script cannot accidentally create 100,000 objects.

Overage and spend caps

Paid plans are postpaid for overage: if you exceed a plan allowance, usage keeps working and is billed after the fact at flat rates.

Overage is reconciled at the close of each billing cycle. An overage invoice under $1 is waived.

Spend cap

Every paid organization has a spend cap that hard-limits overage spending in a cycle:

• The default cap is 2× your plan price — $38 on Starter, $198 on Pro.
• You can self-serve any cap from $0 to $500 in the dashboard. For a higher cap, contact sales@foxnose.net.
• Setting the cap to $0 is a hard stop at your plan allowance: no overage is permitted, and billable requests are refused once the allowance is spent.

When the cap is reached, billable requests return 402 spend_cap_reached — see Boundaries.

Boundaries: reaching a cap or allowance

What an agent or client sees when it hits a limit depends on which limit.

Spend cap reached (paid plans)

A paid organization that reaches its spend cap gets 402 spend_cap_reached on billable requests. This blocks billable reads and writes.

{
  "error_code": "spend_cap_reached",
  "cap_usd": 38.0,
  "cycle_resets_at": "2026-08-01T00:00:00Z",
  "raise_cap_url": "https://foxnose.net/dashboard/billing"
}

There is one exception. If the cap is breached purely by storage growth (data or vector), reads continue to work; only writes return 402. This keeps your published content readable while stopping it from growing further.

Plan allowance exhausted (Free plan)

The Free plan has no overage. When a Free organization exhausts an axis, that axis returns 402 plan_exhausted. This is per-axis — only the exhausted axis is blocked, and the others keep working. Note that this is a 402, not a 429.

{
  "error_code": "plan_exhausted",
  "axis": "retrievals",
  "window_resets_at": "2026-08-01T00:00:00Z",
  "upgrade_url": "https://foxnose.net/dashboard/billing"
}

The axis field is one of retrievals, writes, data_storage, or vector_storage.

Structural limit reached

Creating a structural resource beyond your plan limit returns 403 plan_limit_exceeded, with the offending entity and its limit in detail.

{
  "error_code": "plan_limit_exceeded",
  "detail": {
    "entity": "flux_apis",
    "limit": 5,
    "current": 5,
    "upgrade_url": "https://foxnose.net/dashboard/billing"
  }
}

Over MCP

When a billing block applies, an MCP tools/call returns a JSON-RPC error -32003 carrying the same machine-readable data as the 402 payload above. The MCP handshake (initialize, tools/list, ping) is never blocked, so an agent can still connect and discover tools. See Knowledge MCP.

Accounting windows

• Billing windows are anchored to the day of the month you subscribed — or, on Free, the day you registered. This applies to every tier, including Free.
• Allowances do not roll over. Unused allowance on any axis is not carried into the next window.
• Storage axes are sampled about every 4 hours and billed on the average across the window, as described in Metering axes.

Subscription lifecycle

Payments are handled by Lemon Squeezy. You can pay monthly or annually (annual is 17% cheaper). Cancel, resume, and plan changes are all self-serve in the dashboard.

Payment failures

If a payment fails, the subscription enters a 14-day grace period (past_due) with full service — nothing is restricted during grace. If payment is not recovered by the end of grace, the organization moves to the Free plan.

Downgrades

Downgrading never deletes data. A downgrade only blocks the creation of new resources beyond the lower plan's limits. Everything already stored stays in place and remains readable.

Cancellation

Cancelling keeps your plan active until the end of the paid period, then moves the organization to Free. Your data is retained for at least 90 days.

FAQ

Why was my write charged as 3? Writes are weighted by embedded tokens: write_count = max(1, ceil(embedded_tokens / 500)). Content of about 1,500 embedded tokens is charged as 3 write operations. See Weighted writes.

What does my agent see when it hits a limit? On the Flux API, a paid organization at its spend cap gets 402 spend_cap_reached; a Free organization that exhausts an axis gets 402 plan_exhausted for that axis. Over MCP, a tools/call returns JSON-RPC error -32003 with the same payload, while the handshake keeps working. See Boundaries.

Are failed requests charged? No. Only 2xx and 3xx responses are billed. 4xx, 5xx, 429, and OPTIONS are always free. See What is billed.

Do unused allowances roll over? No. Allowances reset at the start of each window and do not carry over. See Accounting windows.

What happens to my data if I downgrade or cancel? Nothing is deleted. A downgrade only blocks creating resources over the new limits. After cancellation your data is retained for at least 90 days. See Subscription lifecycle.

Does hitting a rate limit cost anything? No. A 429 rate_limited response is free and includes a Retry-After header. Rate limits are separate from metering — see Flux API limits and Management API limits.

Related

• Management API limits — structural limits and rate limits for the authoring surface.
• Flux API limits — rate limits and retrieval behavior on the delivery surface.
• Flux API errors — status codes and error payloads for delivery clients.
• Management API errors — status codes and error payloads for authoring clients.
• Knowledge MCP — what tools/call costs and how billing blocks surface over MCP.