> ## Documentation Index
> Fetch the complete documentation index at: https://docs.checkfu.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Billing
> Understand runtime, model, Tool, and governed-search charges, read Usage, and control admitted spend with Budgets.
Checkfu accounts for agent runtime, managed model use, separately priced
Managed Tools, and governed Web Search. Each follows the terms selected for
the work. Usage records what was metered; a charge records the customer amount.
An invoice or payment is a separate commercial record.
| Service | What the customer pays for |
| - | - |
| Agent runtime | Eligible time when at least one Run in a Session is running |
| Managed model use | Model usage priced under the selected customer terms |
| Managed Tool | A selected operation under its frozen price and billing basis |
| Governed Web Search | Recorded governed `web_search` requests under applicable financial terms |
With API-key BYOK, the model provider bills your account and Checkfu creates no
managed-model charge. Runtime, separately priced Tools, and governed Web Search still follow
their own terms. Customer-operated Cloudflare also does not, by itself, remove the
Checkfu runtime fee. Physical compute and storage costs are separate from the
Session's runtime meter.
Commercial billing and platform supply are `preview` and `rollout_fenced` in
the source registry. A typed billing route or configured model source does
not mean that checkout, entitlement, or Checkfu-funded model capacity is
available to your Workspace. Check the live
[capability status](/getting-started/status) before depending on either.
## Running time
Suppose a support Session has two overlapping Runs, while a second Session
works independently:
| Session | Run | Running interval |
| - | - | - |
| A | First request | 10:00–10:04 |
| A | Second request | 10:02–10:06 |
| B | Independent request | 10:03–10:05 |
Session A records six running minutes, not eight. Session B records two of its
own: eight Session-minutes in total. If A then waits for approval from 10:06 to
10:10 with no Run running, those four minutes add no Session runtime. Its
machine or storage may still incur physical costs during that wait.
Session runtime producer versions 2 and 3 record the union of its running
intervals: overlapping Runs in one Session count once, while different Sessions
count separately. Historical producer version 1 retains its per-Run intervals;
read its original producer version rather than reinterpret that history as a union.
A Run waiting for approval or rescheduling does not itself add running time. If another Run in that
Session is still running, the Session's interval continues; it closes when no Run
remains running. Terminal and settled time do not add running time.
If a crash leaves a running interval without an authoritative close, its end
remains unresolved and the never-closed interval remains unbilled. Restart,
erasure, or a missing response does not supply a billable end timestamp.
Unresolved supplier costs are not thereby zero. Accounting retains the
original interval identity for recovery; an accepted close is retried against
that same Usage identity rather than billed again. These rules do not establish
that a particular outage has been reconciled.
See [Sessions and Runs](/concepts/sessions-and-runs) for lifecycle events and
[Attribute Usage](/guides/attribute-usage#read-authoritative-usage) for retained
runtime versions and attribution.
## The authority split
| Authority | What it answers | What it must not be used for |
| - | - | - |
| **Usage** | What metered work Checkfu recorded | Authorization, policy, or support readiness |
| **Budget or quota** | Whether customer-defined or platform capacity allows more work | Commercial entitlement or payment state |
| **Commercial entitlement** | Whether the Organization may consume paid Checkfu capability | A Workspace's own spending policy |
| **Trace** | What engineers can inspect diagnostically | Billing, Budget enforcement, quotas, or authorization |
Use the [Usage guide](/guides/attribute-usage) to query metered work and its
charges. A Usage row, Budget reservation, billed amount, credit, invoice, and
collected payment answer different questions. None alone establishes all the
others.
The append-only Usage ledger is the metering authority. A trace may project
some of the same activity, but it can be sampled, delayed, redacted, or absent.
Checkfu does not reconstruct authoritative Usage from trace spans, message
text, response timing, or a provider dashboard.
## Model supply and credential custody
A Session freezes its AgentVersion and Environment. The Agent's model config
determines which model source Session admission freezes: a model that pins a
Workspace credential (`model.model_credential_id`) uses that credential, and an
unpinned managed model uses platform supply.
* **Workspace credential:** Checkfu records model Usage and creates no managed-model
charge because the provider bills the Workspace's account. This removes
managed-model charges only; Session runtime and separately priced tools still
follow their own terms.
* **Platform supply:** Checkfu uses an admitted provider account owned by
Checkfu and records the resulting platform charge. Text generation runs on
Checkfu's OpenRouter account, with each managed route pinned to the price
ceiling its rate card was reviewed at; image generation runs on fal.
A Workspace-selected credential never silently falls back to platform supply.
Starting a new Session with a revoked or rejected pinned credential is refused
with HTTP 409 `validation.conflict`; update or rotate the credential before
starting again. If the credential is rejected or revoked for an already-admitted
provider effect, that effect fails closed with `model.credential_rejected`.
Selecting platform supply again is an explicit configuration change for a later
admission.
Raw provider credentials stay in trusted custody. They are not fields in model
context, harness configuration, Session events, Usage rows, or sandbox
workloads. The trusted provider edge attaches the credential only after the
live authorization, policy, approval, Budget, and revocation checks have
allowed the exact effect. See [Security posture](/concepts/security).
## Current metering rules
Usage records activity and its accounting basis. An immutable charge records the
customer amount; delivery to Autumn and payment are separate steps. A pending
billing projection does not mean that the work was free or that payment has completed.
If a delivery loses its response, acceptance can remain unknown. An empty
reconciliation scan or an expired delivery lease does not establish that Autumn
rejected the original event. Checkfu retains the original charge and unresolved
delivery for reconciliation; these observations do not authorize another debit.
For recorded model-token Usage, `measurement.basis: "admitted_maximum"` means the
counters are the conservative maximum admitted before dispatch because no
provider receipt was recovered. These counters are an unreconciled estimate,
not provider-measured consumption. Read the original charge separately; this
basis does not prove supplier acceptance, Autumn delivery, or payment.
Customer charges retain their original rate or formula version and exact amount.
A later rate change or provider change does not rewrite an existing charge.
Supplier costs are separate accounting facts; they are not customer amounts.
A correction links to the original charge and records an absolute target amount
and a signed adjustment. The original charge remains in history. An adjustment's
delivery status does not establish that a credit or cash refund has completed.
Usage without a recorded charge does not, by itself, establish a zero price.
Check its supply class and applicable terms before treating it as BYOK or free
work. A missing financial fact and an undelivered charge are different states.
### Read the charge for a Usage entry
Where the Usage read capability is available, request
`GET /v1/usage/{usage_entry_id}/charge` using the original Usage ID. The SDK
method is `client.usage.charges.retrieve(usage_entry_id, { limit: 20 })`.
This authenticated read returns the retained customer charge and its pricing
version, linked corrections, and the original charge's projection state.
It does not purchase work or activate commercial billing.
Follow `corrections.next_page` as the next request's `page`, keeping the same
Usage ID, Workspace and `limit`. A page is not necessarily the complete correction
history. Each correction includes an absolute target and a signed adjustment;
do not add the absolute targets together. The response's `projection` describes
the original charge, not delivery of each correction or payment. A null `charge`
means no charge is recorded in this read; it does not prove that the work was free.
### Rate versions
The current accounting contracts retain these rates and exclusions. They are
not a universally activated price list; the admitted terms and commercial
availability govern each operation:
| Meter | Charge |
| - | - |
| Session runtime | The retained formula is \$0.08 USD per active Session-hour under admitted financial terms, including customer-operated Cloudflare; a disabled financial disposition records time without a monetary charge |
| Model use with a Workspace credential | No Checkfu model charge |
| Model use with platform supply | Frozen customer rate card when selected; existing default formula uses the admitted supplier rate card × 1.05 |
| Managed Tool | Separately selected immutable customer price and billing basis; an exact-release read exposes offered customer terms when installed |
| Governed Web Search | \$0.01 USD per recorded governed request where this capability and its financial terms are available; native built-in search is not this meter |
Native built-in search does not currently produce the governed `web_search`
meter. It is not billed as a governed Web Search request; runtime and model
usage still follow their own terms. The governed-search rate describes the
existing accounting contract, not universal availability or commercial activation.
The Session-owned native model gateway requires an explicitly selected,
independently frozen customer rate card for managed admission. If that selection
is missing, admission refuses before creating managed supplier or customer holds.
The older model-plane gateway can still use the default supplier-times-1.05
formula shown above; the Session-owned native gateway does not fall back to it.
Historical charges retain their original terms.
Native Sessions retain their runtime financial disposition at creation. Closing
or replaying an interval uses those original terms, not the current billing
switch. The older runtime path uses its enabled-runtime-billing setting. A
disabled native disposition records running time with no billed amount; it is
not permission to enable commercial billing later or reprice that interval.
Managed Tool catalog publication describes a release, not a priced purchase admission.
The exact-release response reports `customer_terms_status`: `available` includes
the observed fixed price, billing basis, empty-result policy, rate-card version
and effective window. `not_installed` or `revoked` returns `customer_terms: null`,
which means no offered quote, not free execution. These read-only terms do not
reserve funds, grant execution permission or authorize a purchase. Admission
retains the applicable original terms separately from catalog discovery.
The product direction is about \$0.08 per active Session-hour and no Checkfu
markup on managed tokens. That direction is not commercial activation. Independent
customer rate cards freeze retail amounts separately from supplier costs for the
selected provider/model pair. Cross-provider model identity mapping is not yet
qualified; changing that pair requires a reviewed mapping and retained customer
price terms. Selecting cards and activating commercial billing are separate
steps; the direction does not change existing charges. Gateway funding and
payment-fee treatment require explicit terms.
Supplier cost estimates, observed liabilities, reconciled supplier invoices,
and supplier payments remain separate from the customer charge. Unknown
liability survives a provider receipt or idempotency window expiring; expiry
does not authorize a fresh paid attempt.
Provider-reported model counters are normalized into immutable model Usage
facts. Actual work remains Usage even when a Session later fails, is cancelled,
or becomes subject to an erasure request.
Sandbox compute and snapshot retention can be recorded for unit economics even
when they are not invoiced. Their presence in Usage does not make them
Budget-enforceable or billable. Included compute and Computer premiums remain
undecided; physical compute, idle residency, and storage do not become Session
runtime charges merely because they incur supplier costs.
When a Principal is erased, retained accounting facts may remain identifiable
or pseudonymous through Workspace and original accounting identifiers. The
direct Principal link is removed and a generated subject reference is retained;
that reference does not establish anonymity. Erasure must not change historical
Workspace totals. Current
end-to-end erasure limits are described in
[Retention and zero-data retention](/concepts/retention-and-zdr).
## Four independent refusal gates
| Gate | Question | Representative error |
| - | - | - |
| Budget or quota | Has a customer limit or platform capacity limit been reached? | `budget.exceeded` |
| Entitlement | May this Organization consume the paid capability? | `billing.usage_limit_reached` |
| Payment | Is the Organization's commercial account in good standing? | `billing.payment_required` |
| Platform supply | Is Checkfu-funded provider capacity admitted and available? | `model.platform_capacity_reached` |
All applicable gates must allow a request. Raising a Budget does not repair
payment or entitlement. Commercial entitlement does not override an
ActionPolicy, a revoked credential, or a Workspace quota.
### Budget admission and stopping
A Budget reserves capacity before work and settles against authoritative Usage.
Live runtime checks include elapsed time in the Session's still-open running
interval within the Budget's scope and window. This counts toward
`session_runtime_ms` and, when billable under the retained runtime terms, the
runtime share of `total_spend`. A Session cannot avoid its Budget merely by
keeping the interval open.
Open accrual is an enforcement projection, not billed runtime Usage. Billed
runtime Usage requires an authoritative close. The closed fact replaces the
open projection, so the same interval is not counted twice.
A prior reservation or approval does not grant unlimited future spending.
Customer Budget capacity and supplier capacity are separate; reserving one
does not reserve the other.
| Metric | What it controls |
| - | - |
| `model_tokens` | Normalized model-token quantity |
| `model_spend` | Recorded model spend where price coverage is available, including catalog estimates and BYOK; not a customer charge or proof of a provider invoice |
| `session_runtime_ms` | Running milliseconds |
| `web_search_requests` | Requests through the governed search path, not unmetered native search |
| `total_spend` | Customer-billable spend plus unresolved original customer exposure during admission |
Spend thresholds use integer micro-USD. BYOK removes managed-model charges from
`total_spend`, not model-cost facts from `model_spend`. Neither metric proves
supplier payment or payment of a customer invoice. See
[Enforce a Principal Budget](/guides/attribute-usage#enforce-a-principal-budget)
for the request shape and scope.
A hard threshold can block new admission, interrupt an in-flight turn, or pause
a Session according to its configured action and supported path. `pause_session`
is valid only for a Session-scoped Budget. Traces do not enforce these limits.
A stop request is not a stop acknowledgment. Observe the original Run's actual
stopped or terminal outcome and the Session's authoritative runtime state. Its
interval closes only when no Run remains running. Do not use a Budget response,
client disconnect, or missing result as the stop time. An in-flight provider operation may already have incurred cost; stopping
the Run cannot undo it. Budget enforcement is not a promise of an instantaneous
hard cap across every provider or physical resource.
For native managed-model work, a `total_spend` Budget includes the retained
maximum customer exposure while settlement is incomplete. This is a spending
control, not an invoice charge or a payment. Expiry or release of the execution
hold does not erase that exposure: the original Usage and its matching frozen
customer charge must both be recorded before the actual charge replaces it.
Usage alone, or a charge for a different original request, customer card, or
credential generation, does not release the bound. An uncertain outcome can
therefore keep capacity unavailable until original financial evidence is
recovered. Retrying must recover that original work rather than buy it again.
An authenticated BYOK model association has zero managed-model customer
exposure. Session runtime and separately priced tools still count according to
their own admitted terms; BYOK does not remove those charges or Budget limits.
## Typed commercial routes
The current contract defines routes such as:
| Route | Contract purpose |
| - | - |
| `GET /v1/billing/status` | Read commercial and supply state |
| `GET /v1/billing/logs` | Read sanitized commercial state transitions |
| `POST /v1/billing/checkout/preview` | Bind a proposed checkout to current catalog facts |
| `POST /v1/billing/checkout` | Start the checkout represented by a preview |
| `POST /v1/billing/portal` | Request a hosted account-management session |
These shapes are API contracts, not a support claim. Call the authenticated
support endpoint and inspect `available` and `missing_prerequisites` before
showing a commercial action.
## Next steps
Query authoritative Usage and attach a Budget to a Principal.
See how permission, policy, approval, revocation, and audit compose.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.