Billing & credits

A credit is the unit Oxygen meters paid work in. One credit ≈ one paid provider call or AI column output. Credits are scoped to one organization.

Credit lifecycle

State	Trigger
Granted	Plan refill or top-up
Reserved	A run starts; estimated cost held against balance
Captured	Run item succeeds with `cost > 0`
Released	Run item fails before billing; reservation returned

oxygen billing balance returns available and reserved.

Managed vs BYOK

Mode	Who pays	What it covers
Managed	Oxygen credits	Oxygen holds the provider API key. Default for enrichment providers.
BYOK	You pay the provider directly	You connect your own provider account. Required for CRMs, outbound sequencers, LinkedIn.

oxygen integrations list --json shows the mode per provider. See Integrations.

Reading balance and usage

oxygen billing balance --json
oxygen billing usage --limit 50 --json

Usage entries include run, provider, tool, credit, and timestamp fields when available. Group by provider or by day:

oxygen billing usage --limit 200 --json | jq '.data.entries | group_by(.provider) | map({provider: .[0].provider, total: (map(.credits) | add)})'

The web app at oxygen-agent.com/billing renders the same data with charts.

Cost estimation

Before running anything paid:

oxygen tools get <tool-id> --json | jq '.estimated_credits_per_call'
oxygen columns run <table-id> <column-key> --limit 1 --json
oxygen workflows templates preflight <template-id> --input-json '{...}' --mode dry_run --json

Spend caps enforce predictability per run.

What's free

Action	Costs credits
`tables query`, `rows history`, `cells inspect`	No
`tools search`, `tools get`, `integrations list`	No
`dry_run` or `smoke_test` of any tool/column/workflow	No
`context profile get/update`, `assets *`	No
`columns add`, `tables rename`, schema changes	No
`oxygen onboarding start`	No for the CLI command itself
Any `live` AI/tool/enrichment column run	Yes (per call)

Failure billing

Failure point	Credit treatment
Pre-billing (auth, validation, 429 before charge)	Released
Post-billing (provider charged then returned error)	Captured
Partial provider cascade	Captured for paid attempts only

Subscriptions

Plans are managed through Stripe. Manage at oxygen-agent.com/subscribe. Plan changes apply at the next billing cycle by default; prorated upgrades available mid-cycle.

Each org has its own subscription and credit balance. Agencies running many client orgs see one balance per org.

Spend caps — per-run limit.
Approvals — gate before credits are spent.
Integrations — BYOK setup.

On this page