> ## Documentation Index
> Fetch the complete documentation index at: https://usenaive.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Credits
> Usage-based billing — how credits work, costs per operation, sync vs async charging.
## CLI First
```bash theme={"theme":"css-variables"}
# Check usage and buy more credits
naive usage --days 30
naive billing packs
naive billing topup --pack medium
```
## How Credits Work
Every company has a credit balance. Operations deduct credits on use. New accounts start with **1 free credit** on a 7-day starter trial.
## Credit Costs
Each credit is worth **\$0.05 USD**.
### Fixed-Price Operations
| Operation | Credits | Charging |
| ------------------------------------------------------- | ----------------- | --------------------------------------------------------------- |
| Email send | 10 | Immediately on success |
| Web search | 10 | Immediately on success |
| URL read | 10 | Immediately on success |
| Research (quick) | 30 | Immediately on success |
| Research (thorough) | 50 | On job completion |
| Research (exhaustive) | 80 | On job completion |
| CEO run (pre-check) | 5 | Pre-check on run start (downstream LLM/tools billed separately) |
| SEO keywords / on-page | 10 | Immediately on success |
| SEO Labs / backlinks (bulk) | 20–50 | Immediately on success |
| AEO endpoints | 20–30 | Immediately on success |
| app-data / business-data | 10–20 | Immediately on success |
| ecommerce | 20 | Immediately on success |
| Clips (submagic): create / edit | 40 / 30 | On completion |
| Social post | 10 | Immediately on success |
| SMS send (phone) | provider cost × 2 | Immediately on success |
| Phone number provision | provider cost × 2 | On success (irreversible, approval-gated) |
| Stock photo search | 0 | Free |
| Browser session open | 0 | Free (time floor billed at close) |
| Browser navigate / act / extract / observe / screenshot | 10 each | Immediately per action |
| Browser autonomous signup | 40 | On success (approval-gated) |
| Browser autonomous login | 30 | On success |
| Browser session time floor | 10–30 | At close, by elapsed time (≤5 / ≤15 / ≤30 min) |
SEO / AEO / queue are additionally metered against your **plan quota** (a separate
per-primitive counter surfaced at `GET /v1/users/:id/billing/usage`) on top of the
credit charge above.
### Infrastructure (duration-metered)
Anything that runs a **server you keep alive** is billed by time, not per call —
metered continuously by a background scheduler (\~every 2 minutes) and debited via
the same idempotent ledger. Scale-to-zero means an idle/stopped resource accrues
nothing.
| Resource | Action type | Rate (default) | What's billed |
| ------------------------------------------------------------------------- | --------------- | ---------------------------------------------- | ------------------------------------------------------------ |
| **Compute** (`compute` primitive — your managed compute tasks & services) | `compute_usage` | 20 credits / vCPU-hour + 2.5 credits / GB-hour | While a run is `running` or a service has `desiredCount > 0` |
| **Hosted runtime** (a Naïve-hosted agent profile agent / `runtime.start`) | `runtime_usage` | 20 credits / vCPU-hour + 2.5 credits / GB-hour | While **your** agent profile's Hermes container is `running` |
* The hosted-runtime container is `1 vCPU / 2 GB` by default, so a continuously-running
hosted agent costs ≈ `20 + (2 × 2.5) = 25 credits/hour` (\~$1.25/hr at $0.05/credit).
* Only **claimed** containers (your agent profile's) are billed. The shared warm pool that
keeps start-up latency low is **platform overhead and is never charged to you**.
* Bring-your-own-runtime (you run the agent in your own harness with `agentProfile.tools()`)
incurs **no** `runtime_usage` — you only pay for the API primitives the agent calls.
* A claimed hosted container bills the same whether busy or idle (the task is up), so
tear agent profiles down with `revoke()` when done — revoke releases the slot immediately.
**Path A infrastructure is credit-gated.** Provisioning via `naive up` (managed
Postgres, object storage buckets, web hosting) is blocked when your credits are
exhausted, and when you run out, running infra is shut down (web disabled,
runtime/compute stopped). Database and bucket **data persists** — top up to
resume; new provisioning unblocks immediately.
### LLM Calls
There are two ways LLM usage is billed, both per-token and deducted after the call completes (after the final SSE event for streams):
* **The `llm` primitive & OpenRouter proxy** (`POST /v1/llm/chat/completions`, `naive.llm.chat()`, and the `/v1/proxy/openrouter/*` drop-in). These route through [OpenRouter](https://openrouter.ai), which returns the exact USD cost of each call. Naive bills that returned `usage.cost` × markup, converted to credits — so there's no per-model rate table and pricing always tracks OpenRouter. See the [LLM primitive](/docs/getting-started/llm).
* **Orchestration LLM calls** (CEO agent / employees). These flow through the Anthropic/OpenAI/Google proxies and are billed per-token using the rates below, with cache read tokens billed at a discount and cache creation at a premium.
| Model | Input (per 1M tokens) | Output (per 1M tokens) |
| --------------------- | --------------------- | ---------------------- |
| Claude Opus 4.5 | 125 credits | 625 credits |
| Claude Opus 4 | 375 credits | 1875 credits |
| Claude Sonnet 4 / 4.5 | 75 credits | 375 credits |
| Claude Haiku 4.5 | 25 credits | 125 credits |
| Claude Haiku 3.5 | 20 credits | 100 credits |
| GPT-4o | 62.5 credits | 250 credits |
| GPT-4o Mini | 3.75 credits | 15 credits |
| Gemini 2.0 Flash | 1.875 credits | 7.5 credits |
| Gemini 2.5 Pro | 31.25 credits | 250 credits |
LLM costs are deducted automatically after each API call completes. For streaming responses, usage is extracted from the final SSE event and deducted post-stream. Built-in web search tool use is also billed when used.
### Dynamic-Price Operations (Image/Video Generation)
Image and video generation costs are **model-dependent** and calculated dynamically. Use the pricing endpoints to preview costs before submitting:
```bash theme={"theme":"css-variables"}
GET /v1/images/pricing?model=fal-ai/flux/schnell&num_images=2
GET /v1/video/pricing?model=fal-ai/kling-video/v3/pro/text-to-video&duration=5
```
Response:
```json theme={"theme":"css-variables"}
{
"model": "fal-ai/flux/schnell",
"estimated_credits": 1.2,
"unit_price_usd": 0.02,
"credit_value_usd": 0.05
}
```
## Two different "budgets" — don't confuse them
Naïve has **two independent ledgers**. Keep them straight:
| | **Platform credits** | **AgentProfile budget** |
| ------------------- | ---------------------------------------------------------- | --------------------------------------------------------- |
| Question it answers | "What do I owe Naïve for usage?" | "How much real-world money may this agent spend?" |
| Unit | Credits (\$0.05 each) | USD cents |
| Ledger | `credit_transactions` (company-wide) | `tenant_spend_events` (per agent profile) |
| Covers | LLM, search, email, images, compute, **hosted runtime**, … | Card limits, card top-ups, trading notional |
| Set by | Your plan + top-ups | An agent profile template's `policy.budget` |
| Enforced by | `checkCredits` (402 `insufficient_credits`) | The governance gateway (`403 budget_exceeded` / approval) |
An agent profile's `budget.cap` is a **combined cost ceiling**: it caps the agent profile's
real-world spend (cards/trading) **plus** the platform credits it burns (LLM, search,
compute, hosted runtime — counted at \$0.05/credit) against one number. It is still
distinct from your company-wide Naïve credit balance (the budget is per agent profile, in
USD). A **hard** cap denies over-budget actions (and auto-stops the agent profile's hosted
runtime); a soft cap routes them to approval. See [IaC policy](/docs/getting-started/iac)
and the [Governance Gateway](/docs/architecture/governance-gateway).
### Running out of credits
When a company's credit balance is exhausted, new API calls return `402
insufficient_credits` and **hosted-runtime containers are automatically stopped** by
the meter (a `runtime.stopped` event with `reason: out_of_credits`) — so a
non-paying account stops incurring cloud cost. Top up or upgrade to resume.
## Sync vs Async Charging
**Synchronous operations** (email, search, URL read, quick research):
* Credits deducted immediately when the operation succeeds
* If it fails, no credits are charged
**Asynchronous operations** (images, video, thorough research):
1. On submission: pre-check that balance ≥ estimated cost (returns `402` if not)
2. Job runs in background
3. On success: credits deducted and transaction recorded
4. On failure: no charge
Concurrent async jobs can temporarily exceed your balance since pre-checks pass independently. The balance may go slightly negative — subsequent submissions will be blocked once balance drops below threshold.
## Checking Your Balance
```bash theme={"theme":"css-variables"}
GET /v1/status
```
Returns your current balance, tier, and resource counts.
## Usage History
```bash theme={"theme":"css-variables"}
GET /v1/usage?days=30&limit=50
```
Returns transaction history with action type, amount, and reference IDs. Every charge
type appears here keyed by `action_type` — e.g. `llm_call`, `web_search`,
`email_send`, `job_completion`, `compute_usage`, `runtime_usage`,
`subscription_renewal`, `credit_topup`. The dashboard's
`GET /v1/dashboard/usage-summary` groups the same ledger by `action_type` so you can
see exactly where credits went (including infrastructure time).
## Credit Responses
Every operation that costs credits includes the charge in its response:
```json theme={"theme":"css-variables"}
{
"credits_used": 10,
"credits_remaining": 990
}
```
For async jobs, the estimated cost is shown on submission:
```json theme={"theme":"css-variables"}
{
"job_id": "uuid",
"estimated_credits": 20,
"hint": "Credits charged on completion only."
}
```
## Credit Enforcement
All billable operations check your credit balance before executing. When your balance drops to zero or below:
* **API primitives** (email send, search, URL read) return `402 insufficient_credits`
* **CEO runs** are blocked with a credit pre-check (5 credits)
* **LLM proxy calls** from the container are rejected, stopping agent work
* The balance has a small negative buffer (-100 credits) to avoid cutting off mid-stream responses
Credits are enforced at every layer — the API, the LLM proxy, and individual primitive endpoints.
## Running Low on Credits?
When your balance hits zero, operations fail with an `insufficient_credits` error that includes available credit packs. You can buy more anytime:
```bash theme={"theme":"css-variables"}
# See available packs
naive billing packs
# Buy credits
naive billing topup --pack medium # 500 credits for $23
```
Or upgrade your plan for more monthly credits:
```bash theme={"theme":"css-variables"}
naive billing upgrade --plan pro # 2000 credits/mo
```
See [Billing & Credits](/docs/getting-started/billing) for full details on plans and pricing.
## Configuration reference (rates & metering)
The credit value and the duration-meter rates are deployment configuration. On the
managed cloud these use the defaults below; self-hosters can override them via
environment variables.
| Setting | Env var | Default | Notes |
| ------------------ | ------------------------------------- | --------------- | ---------------------------------------------------------------------------------- |
| Credit value | — | \$0.05 / credit | Retail value used across the rate tables. |
| Compute vCPU rate | `NAIVE_COMPUTE_CREDITS_PER_VCPU_HOUR` | `20` | `compute` primitive duration meter. |
| Compute GB rate | `NAIVE_COMPUTE_CREDITS_PER_GB_HOUR` | `2.5` | `compute` primitive duration meter. |
| Runtime vCPU rate | `NAIVE_RUNTIME_CREDITS_PER_VCPU_HOUR` | `20` | Hosted-runtime (Hermes) duration meter. |
| Runtime GB rate | `NAIVE_RUNTIME_CREDITS_PER_GB_HOUR` | `2.5` | Hosted-runtime (Hermes) duration meter. |
| Hosted task size | `ORCH_TASK_CPU` / `ORCH_TASK_MEMORY` | `1024` / `2048` | vCPU-millis / MB of the orchestration task; used to compute runtime vCPU/GB-hours. |
| LLM markup | — | ×1.25 | Applied to OpenRouter's returned USD cost. |
| Image/Video margin | — | ×2.0 | Applied to the live fal.ai price. |
Both duration meters tick every \~2 minutes, key each charge to a time window
(`:`) so a double-tick can't double-charge, and cap a
single tick's back-charge at 3 intervals if the scheduler was paused. Compute is
gated on `NAIVE_COMPUTE_*`; hosted-runtime metering is gated on `ORCH_CLUSTER`
(hosted runtime being enabled at all).