> ## Documentation Index
> Fetch the complete documentation index at: https://webscraping.titannet.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Credits and billing

> How credits, wallets, plans, and usage debits work in Titan, and which APIs expose them.

Credits and plans are handled by **billing**, separate from the task service that creates tasks and runs executions. Usage from runs flows into billing as events that become **ledger entries**, **activity**, and **spend summaries**. Dollar amounts, allowances, and paid tiers depend on **how your Titan environment is configured**; this page describes the **model** and the APIs you use to inspect it.

## Wallet and balances

Billing is the source of truth for what you can spend. A typical balance response includes:

* **`total_available`** — spendable credits across buckets
* **Named buckets** (for example daily free allowance, monthly plan credits, or promotional credits—the exact labels and fields depend on your environment)
* Optional breakdowns such as active credit **lots** or **refresh** metadata when your environment exposes them

Use **`GET /api/v1/billing/balance`** (see the **Billing API** group in the API Reference tab) to read the current wallet. Query parameters such as `include_active_lots` and `include_refresh_meta` request optional sections when supported.

## Ledger and activity

To answer “what consumed credits?” use:

* **`GET /api/v1/billing/ledger`** — filtered ledger lines (time range, task, execution, direction, reason code, pagination)
* **`GET /api/v1/billing/activity`** — a higher-level activity feed with similar filters

Both are read-only and require the **`billing:read`** scope (or equivalent for your API key).

## How credits are charged (conceptually)

There is **no** single global rule like “one credit equals one HTTP call” in the task API. Charging follows **pricing rules** your operator configures: the platform records chargeable work, and the active policy decides how many credits to debit for a given URL, step, retry, or phase of an execution.

Rough **areas** that often affect debits (exact reason codes and labels vary by environment):

| Area               | Role in debits                                                                                                                         |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| **Execution work** | URLs processed, retries, action complexity, and lifecycle of multi-step tasks (several charge points over one run are possible).       |
| **Action types**   | `search`, `crawl`, `scrape`, and `api_call` draw from the same wallet; cost per step follows your pricing rules.                       |
| **Previews**       | Task and template previews run real work under stricter guardrails; they may still consume credits where your product applies charges. |
| **Refunds**        | When enabled, rules depend on your billing configuration (see refund-related fields in billing API responses).                         |

For rollups tied to work you already ran:

* **`GET /api/v1/billing/usage/executions/:execution_id/spend-summary`**
* **`GET /api/v1/billing/usage/tasks/:task_id/spend-summary`**

For calendar views:

* **`GET /api/v1/billing/statements/monthly?month=YYYY-MM`**

## Plans and catalog

* **`GET /api/v1/billing/plans`** — plans exposed in your environment (credit allocations and **prices in cents** per row).
* **`GET /api/v1/billing/plan`** — your current subscription and plan definition.
* **`POST /api/v1/billing/plan/select`** — body `{ "plan_id": "<id>" }`, requires **`billing:write`**. Response shapes can vary slightly by environment; see the Billing API in the API Reference for details.

## Free tier and production pricing

**Development or demo** environments sometimes ship with a **free** plan that includes a **monthly** credit allowance (on the order of a few thousand credits), **no per-use charge** for that tier, and simple defaults for how credits accrue or expire. **Production** plans, enterprise contracts, and exact numbers are **not** assumed here.

For what actually applies to **your** account, use **`GET /api/v1/billing/plans`**, **`GET /api/v1/billing/balance`**, and your **public pricing** or contract—not static numbers in documentation.

## Relationship to analytics

Usage dashboards read from **analytics**; billing answers “what was charged against the wallet?” When reconciling runs with debits, use the same **task IDs** and **execution IDs** across analytics, billing, and the task service.

## Related reading

* [Rate limits](/about-platform/rate-limits) — API request limits and preview quotas alongside billing.
* [Executions](/about-platform/executions) — where chargeable work is produced.
* API Reference → **Billing API** — balance, ledger, usage, and plans.