> ## Documentation Index > Fetch the complete documentation index at: https://docs.karta.sh/llms.txt > Use this file to discover all available pages before exploring further. # Usage, cost & budgets > How Karta meters tokens and cost, the reports and alerts you get, and the hard caps that return 402 before you run over budget. Every turn is metered, and every organization has a budget. Karta tracks what your agents cost, lets you set caps that stop spend before it happens, and returns **402 Payment Required** when a cap is hit - no surprise bills. ## What's metered Each agent turn records **input tokens and output tokens**, attributed to the organization and, when available, the API key, karta, and verified acting user involved in the turn. Total tokens and cost are derived - cost from the per-model rates on the [rate card](/platform/billing-and-credits#rate-card). Metering is **best-effort and never blocks your agent's response**: usage is buffered and flushed in the background, and successful retries are de-duplicated so nothing is double-counted. Under a management-service outage or extreme load, a small fraction of events may be dropped. ## Budgets and cost thresholds An organization budget can cap **input tokens, output tokens, total tokens, and cost**. API keys can also carry sub-limits for input tokens, output tokens, and cost, so one integration cannot burn the whole budget. Enforcement gates on two things: 1. **Subscription status** - an inactive subscription blocks consumption. 2. **Caps** - any configured limit being exceeded blocks consumption. When a cap is crossed, the next request returns: ```json theme={null} HTTP/1.1 402 Payment Required { "error": "budget_exhausted", "message": "Organization budget exceeded", "reason": "total_tokens_cap_reached" } ``` ```bash theme={null} # A request once the cap is hit: curl https://api.karta.sh/v1/sessions/$SID/messages \ -H "Authorization: Bearer $KARTA_API_KEY" \ -d '{"text":"hi"}' # -> 402 { "error": "budget_exhausted", "reason": "..." } ``` Enforcement happens before new work starts. Usage metering is asynchronous, so a turn already in flight can finish; the next gated request sees the updated budget state. ## Karta-grain caps Beyond the organization budget and API-key sub-limits, you can cap spend at the same grains your product uses to create kartas: * **Per user** - a hard monthly cap on one verified user, across every per-user karta they use. Set it from the **End-users** page. * **Per karta** - a cap on one durable karta, such as a virtual employee or backend worker, summed across everyone or everything using it. Set it from the **Kartas** page. * **Per seat** - a cap on one verified user's spend *inside* a shared virtual employee karta, also set from the **Kartas** page. All of them are hard caps: when one is reached, the next request at that grain is refused before it runs - a `402` on the API, or a graceful [`limit_reached`](/security/chat-widget#graceful-limits) state in the embedded widget. Caps you have not set never block anything. Every cap in effect - organization, API key, per-user, per-karta, per-seat, and the per-embed-key anonymous ceiling - is listed together on the **Limits** page (and on **Usage**), each linking to where you set it. Start there to see what's capped and what is not. ## Credits and the prepaid gate On managed plans, usage draws down a **prepaid credit balance** - there is no metered overage and no invoice. When the balance runs out, requests return `402` with reason `credits_exhausted` until you top up. Bringing your own model key ([BYOK](/platform/byok)) means you pay your provider directly for model tokens, but Karta's platform fee still draws down the same prepaid balance - so the `credits_exhausted` gate applies there too. See [Billing & credits](/platform/billing-and-credits) for plans and packs. ## Threshold alerts Register a [webhook](/platform/webhooks) to be notified as you approach or cross a budget threshold (and on billing events). Use it to raise a cap, alert a team, or throttle traffic *before* you hit a hard stop. ## Reading usage & cost ```typescript theme={null} import { Karta } from "@karta.sh/sdk"; const karta = new Karta({ apiKey: process.env.KARTA_API_KEY! }); const usage = await karta.usage.summary(); // period totals + budget const billing = await karta.billing.status(); // subscription state ``` ```bash theme={null} karta usage # via @karta.sh/cli - current period totals + budget ``` Use these for cost reporting and capacity planning - track period-over-period spend, attribute cost to individual keys, and forecast against your caps. Per-key sub-limits and scopes. Get notified on budget thresholds and billing events.