acted_as when creating the Session.
Checkfu validates that delegation at admission. Keep API keys server-side;
do not forward an unchecked Principal ID from a browser or model.
Usage is
alpha and intended for the hosted control plane, but live
readiness is deployment- and Workspace-specific. Check
capability status before making Usage or Budget
availability part of your application’s contract.Plain HTTP against the Checkfu API needs no private package.
The documented path is usable as written for an admitted Workspace.
Confirm capability status before making availability part of your application’s contract.
Create a Session for a Principal
SetCHECKFU_PRINCIPAL_ID to an active Principal in the API key’s Workspace.
That Principal needs effective act_as permission on the selected Agent.
The Agent also needs permission to use CHECKFU_ENVIRONMENT_ID. See
Session identity and
Permissions for setup and delegation checks.
Choose a unique idempotency key for this logical Session; usage-session-482
below is an example. Keep that key and the complete request body unchanged
when retrying, including after a lost response. Use a new key only to create
a separate Session.
acted_as retains that Principal for
Usage attribution and Principal-scoped Budgets. Without acted_as, a direct
Workspace-key Session has no Principal attribution. If the Agent has governed
Connection bindings, omitting acted_as is refused. An unknown, inactive, or
unauthorized Principal is also refused with 403 policy.denied.
Delegation does not change the API key’s Workspace or grant access to a
Connection. Resource permissions, policy, approval, and current authority still
apply. The unsupported principal body field remains rejected with
400 validation.malformed; use the authorized acted_as field instead.
The Session freezes the selected AgentVersion and Environment. Its Runs,
governance decisions, Audit records, and Usage facts retain the same
attribution lineage.
Read authoritative Usage
GET /v1/usage returns immutable metering facts. Filter by the dimensions
defined by the current wire contract, including Principal, Agent, surface,
Automation, Session, and Run, and follow the opaque next_page cursor.
These are customer wire variants, not a promise that every capability is available
to your Workspace. Managed Tool supplier costs stay in internal accounting and
are omitted from the customer Usage response. A recorded measurement is separate
from its charge and payment; see Billing and Usage.
For Session runtime, producer versions 2 and 3 record the union of the Session’s
running intervals. Overlapping Runs in one Session count once; different Sessions
count separately. Retained version 1 facts use historical per-Run intervals and
are not rewritten into union facts.
Native runtime uses producer version 3 and placement
cloudflare_durable_object.
Its Usage retains the actual Run with attempt: null; its matching runtime charge
retains that Run with attempt_id: null. A null attempt does not mean that the work
was unpriced or unrecorded. The runtime charge’s formula and amount remain separate
from Usage and from supplier compute costs. This wire contract does not establish
that runtime billing is enabled for your Workspace.
Lightweight Check calls use the same model measurement. Their evaluation
field identifies the owning parent and operation slot; run and attempt
are null. Session and Agent attribution is present only when the evaluation
belongs to an existing Session. A standalone classification does not create
an Agent Run just to account for model usage.
Supply classification, candidate identity, provider counters, rate identity,
and monetary facts are server-owned fields. Do not rebuild them from model
messages or client labels.
Read the charge for a Usage fact
Use the original Usage row’sid to read its retained customer charge:
usage_entry_id to its charge, linked corrections, and
optional billing projection. A charge retains its original pricing identity,
amount in micro-USD, and fractional remainder. It does not select today’s rate or
expose supplier credentials or supplier invoices.
Corrections are paginated separately: pass corrections.next_page as the opaque
page query parameter on this same route; limit accepts 1–100. A correction
retains the original charge id, absolute target amount, and signed adjustment.
It does not overwrite the original charge or establish a completed cash refund.
charge: null means no customer charge is present in this readback; it does not
establish that all work was free. BYOK removes managed-model charges, while runtime
and separately priced tools follow their own terms. A projection’s mutable
state describes Autumn delivery, not invoice or payment completion. Check live
capability status before relying on deployment readiness.
Read Usage series coverage
Usage series separate metering totals from monetary totals. Thespend_coverage fields are coverage counts, not dollars or token counts:
These counters describe model coverage; they are not a census of every runtime,
tool, or storage fact. A priced measurement can remain
unknown until its
customer charge is linked. BYOK excludes managed-model charges, not unrelated
platform charges. Coverage does not establish payment or supplier settlement.
A Usage bucket has spend_status: partial when its projection is partial or it
contains unpriced or unknown coverage. Otherwise it is complete when charged
coverage exists, and not_applicable when it does not. Monetary buckets expose
complete or partial separately. Missing money is not proof of zero spend;
check coverage and projection freshness before interpreting totals.
With group_by: agent_definition, the group value is the immutable Agent id,
not an Agent version id or display name. none means the fact has no Agent
attribution; not_applicable means a dimension does not describe that fact.
Failures, cancellation, and later erasure do not delete work that was actually
metered. Principal erasure removes direct Principal attribution and replaces it
with a generated subject reference. Retained accounting identifiers and links to
the Workspace, Session or Run may remain identifiable or pseudonymous; historical
accounting facts and Workspace totals are preserved.
Read time series
GET /v1/usage/series returns server-owned UTC-day buckets for its bounded
range. Spend and Usage are separate projections. Treat a partial watermark,
incomplete result, or partial spend status as known data, not as zero and
not as a complete invoice.
The route combines qualified rollups with a bounded raw tail. It fails closed
when the required projection cannot be established; it does not silently ask
the client to scan an unbounded history. Use the generated API reference for
the current grouping values rather than persisting a retired resource name in
your product model.
Usage, traces, and invoices
A trace can be useful for debugging latency or model behavior. It cannot
enforce a Budget, quota, bill, PermissionAssignment, ActionPolicy, or
ActionApproval. Missing trace spans do not reduce Usage, and duplicate-looking
trace spans do not create Usage.
Enforce a Principal Budget
A Principal-scoped Budget applies the same limit to every Session attributed to that Principal.model_spend tracks model cost where price coverage is available, including
Usage with a Workspace credential. These costs can differ from the customer charge.
Use total_spend for customer-billable spend; admission also counts unresolved
original customer exposure. BYOK excludes managed-model charges from this total,
while runtime and separately priced tools follow their own admitted terms.
Neither metric establishes supplier payment or customer invoice payment.
A hard threshold can block admission. Where the typed Budget action permits it,
the configuration can also interrupt an in-flight turn. Reservation and
settlement use the authoritative Usage path, not traces.
Admission checks also account for unresolved original customer exposure where
needed to preserve the cap. This held capacity is not an invoice, charge or
payment. Matching original financial settlement replaces the exposure; an
expired execution lease alone does not establish that the work was free.
429 budget.exceeded is a shared capacity error. It can represent a Budget,
Workspace quota, ToolInvocation ceiling, or API-key rate limit. Present it as
“limit reached” unless the structured response identifies the exact source.
Keep the gates separate
Remaining Budget does not grant permission. Permission does not extend
commercial entitlement. Every applicable gate must allow the work.