Pricing & usage
Explanation — what & why
Vectros is credit-based, pay-as-you-go: you are metered on what you actually do, and a single usage report shows where you stand. There is no seat licence to buy before you can make a call, and every plan includes a large monthly read allowance — so exploring and serving your own data is not what drives cost.
Usage is metered on two axes, kept separate on purpose because data-plane work and model inference have very different cost structures:
- A monthly credit allowance covers data-plane work — record writes, document ingests (including the indexing they trigger), deletes, searches, reads beyond your plan's included read and data-out allowances, the execution time of your trigger scripts, the per-call platform fee of each inference call (0.2 credit for a call of up to 60 seconds, then 1 credit per 5 minutes of the call's duration), and the platform fees of agent runs (see Agent runs below). It resets each calendar month, and the usage report tells you how much of the period's allowance you have consumed.
- A pre-paid inference balance covers AI calls — chat, RAG, and
document-ask, and the model calls of agent runs. It is a ledger, denominated in
cents and kept to the thousandth of a cent (milli-cents), that draws down as you
make inference calls and is topped up out of band. It does not reset
monthly the way the credit allowance does. New balance-billed accounts start at $0, so the
first AI call returns a
402until the balance is funded. Funding needs a paid plan and is done in the developer portal under Usage → Inference balance — every non-inference operation works without it. Among the outcomes of the balance step, only402means that the balance is short. A call whose balance step could not complete is not a shortage:429witherrorCodeBALANCE_BUSYmeans the balance is momentarily busy with other concurrent requests of yours, and503witherrorCodeBALANCE_UNAVAILABLEmeans a temporary service fault interrupted that step. Do not top up for either; retry after the seconds in theRetry-Afterheader. The model is not called in any of the three cases. A call you route to your own model provider (providerAlias) is billed to you by that provider, not by Vectros. It takes no pre-paid balance hold, deducts no token cost, and skips the monthly credit-limit and inference-balance (or usage-cap) checks; the burst rate limit still applies. Vectros still records the call and the per-call platform fee, and a routed RAG call also records the standard search-query charge for its retrieval step.
What an inference call costs. Two parts, reported separately on the call's done event.
The token cost is the call's input and output tokens at the model's per-token rates (the model
catalog lists them), drawn from the inference balance in milli-cents and never rounded to whole
cents (inferenceBalanceCentsChargedMilli). On a model with prompt-cache prices, tokens served from or
written to the provider's prompt cache are charged at its cache rates instead of the input rate. The
platform fee counts against the monthly credit allowance (platformCreditsCharged): 0.2 credit
for a call that lasts up to 60 seconds, then 1 credit per 5 minutes of the call's duration,
prorated (a call of 120 seconds is 0.4 credit). One credit is one cent. A call that fails on our
side before it produces any output carries neither charge.
Agent runs. A run's model calls draw the inference balance in milli-cents. A run is served on
the model's US profile, so the region premium (regionPricing.regionPremiumFactor in the model
catalog) is billed on every model call of a run, and the long-prompt rate applies where the model has one.
Cache reads and writes inside a run are charged at the model's input rate, not at its
cache rates. A run's budget bounds these model charges. Everything else is charged to the monthly
credit allowance, and a model call inside a run carries no per-call platform fee of its own:
- Per run: 0.2 credit.
- Run time: 1 credit per 5 minutes of the run's duration. A fraction of a credit carries over to the next run in the period, so many short runs are not rounded down to nothing.
web_fetch: a fixed fee for each successful fetch.web_search: 1 credit for each successful search.
The tool calls a run makes on your data (reads, searches, writes) are billed as the same calls made directly.
A run that is cancelled before it starts running is charged nothing from the credit allowance. The agents and runs reference has a run's budget, limits and errors.
A property worth designing around: reads are effectively free at the volumes
most applications target. Every plan includes a large monthly read allowance
(and a data-out allowance) that grows with your tier; within it, reads draw
nothing from the credit allowance, and plain GET reads are exempt from the
per-tenant business rate limit either way. Search calls and POST lookups
still count against that rate limit. Writes, deletes, searches, read overage, and
script execution time (trigger firings and synchronous executions) count against the allowance; only inference
draws down the balance. So a read-heavy application is cheap to run on the data
plane, and the cost you should reason about is the cost of writing and
asking, not the cost of reading back.
Trigger scripts are charged for the execution time they do not earn back. A trigger script runs your code for a variable span, while everything else here is priced per operation — so a script that runs for a long time while performing few or no billable operations does not cover the compute it consumes. Execution time is therefore metered, and the charge is built so you can check it:
- Script execution bills at a flat rate per second, measured over each execution's whole span — resolving the rule, preparing the sandbox, running your code and recording the outcome are all inside it, so the span is legitimately longer than your script's own run time.
- Most billable operations your script performs include execution time at no extra charge, and that included time is earned by the fee the operation already paid — it is not a separate allowance you can run out of. A record write, a document ingest and a read charged as overage each include a different amount, because they are priced differently — a read inside your plan's allowance is charged nothing, so it includes nothing. The exact total applied is reported back to you, so you never have to reconstruct it.
- Each execution also carries a small fixed platform baseline, which covers the cost of running an execution at all (the queue hop, the idempotency writes, the dispatch reads).
- You are charged only for time beyond what your operations included. A script that does real work and finishes promptly typically owes nothing at all; what this charge reaches is a script that spins, sleeps, or waits.
Three consequences worth designing for.
A read-heavy script inside its read allowance includes nothing. Those reads are charged nothing, so there is no fee for them to have earned included time from, and the script pays for its own span. Data-out (egress) overage likewise includes no execution time.
A firing we refuse before your script runs is never charged — a rate limit, a credit ceiling, a concurrency limit, a rule whose grant or script does not resolve, a deleted rule — and neither is an execution that fails on an internal platform error of ours.
But once your code is running, the span is charged whatever the outcome. Your script throwing, a timeout, a resource or write-buffer limit, a write conflict, or a call your script made that its permissions or declared manifest did not allow. Those last ones are decided while the script runs — a script can probe, recover, run for minutes and still be reported under them — so do not read them as refusals. The line is not "did it succeed" but "did your code get to run".
Writes and deletes cost the same. Deleting a record or document is itself a write — the item, its lookup rows, and its index entries all change — so a delete charges the standard write fee (the same base and per-index charges a write pays; for documents, the one-time ingest fee applies only when content is ingested). This applies to individual deletes and to tearing down an app context. Closing your account is different: account offboarding and full-tenant deletion are always free.
Usage is also broken down per environment. Your account totals are the sum of your live tenant and your test tenant, each reported separately, so you can see what production traffic costs versus what your test traffic costs — and the two reconcile up to the account total, for a credential with cross-context reach. Test traffic is metered like production, so a noisy test loop shows up in the report rather than hiding.
A credential confined to a single app context sees only that context's usage — its totals narrow accordingly, not the account-wide sum. See the Operations & trust reference for the exact narrowing contract.
How-to — read what you are using
Pull the current period's consumption — the monthly credit allowance and the pre-paid inference balance — in one call:
const usage = await client.auth.getUsage();
console.log(usage.credits.used); // whole credits used this period
console.log(usage.credits.usedMilli); // exact figure in milli-credits (1 credit = 1000)
console.log(usage.inference.balanceCentsMilli); // inference balance in milli-cents (1 cent = 1000)
console.log(usage.inference.totals.cacheReadTokens); // input tokens served from the prompt cache
getUsage returns the report object directly — it is not wrapped in the list
envelope and does not paginate. Pass a { year, month } to read a prior period.
The full report shape (per-environment breakdown, the inference balance, and the
limits) is in the Operations & trust reference;
the step-by-step is in the Operations & trust how-to.
Access to the report is itself scoped: a token needs the billing:r
permission to read it. That lets you hand a read-only billing view to an internal
dashboard without granting it any data access — a token scoped to, say,
records:r cannot read your billing figures.
Notes & limits
- Qualitative here by design. This page describes the model — what is
metered, on which axis, and how to read it. The per-call and per-run platform fees above are
stated here; the monthly credit allowance is not pinned in the docs,
so a stale number never ships here. The monthly credit allowance is quoted at sign-up and in
your account. The per-model token rates, including the US-served rate, any long-prompt rate
and any prompt-cache rate, are listed in the model catalog
(
GET /v1/models; see Prompt-length pricing and Prompt-cache pricing) and shown in the model pickers. - Reads are free within a generous allowance; writes, deletes, searches, and inference are not. Architect for that asymmetry — cache nothing you can re-read, but batch writes where you can, and treat delete churn as write churn.
- Keep trigger scripts short, and do the work rather than waiting for it. Execution time is the one charge here that is not proportional to what you stored or fetched, so it is also the one a bug can run up: an accidental spin loop bills for its whole span. It is bounded — the charge draws the same monthly credit allowance every other operation draws, so a runaway script hits your credit ceiling and stops firing rather than billing indefinitely (on a plan that has a ceiling — an unlimited plan has no such backstop).
- The axes are reported separately, and an inference call touches both. Its
token cost comes out of the inference balance; its per-call platform fee counts against
the monthly credit allowance. A plan whose monthly credit ceiling is used up refuses
inference calls with
402anderrorCode: "SUBSCRIPTION_LIMIT_EXCEEDED"even when the balance is positive (a call routed to your own provider skips that check). Running out of balance does not consume the monthly allowance.
Where to go next
- Operations & trust — how-to — read the usage report and hand a billing-only view to a dashboard.
- Operations & trust — concept — the usage and billing model in full, alongside the rest of the trust posture.
- Quickstart — make your first metered call.