Skip to main content

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.

Every turn is metered, and every org has a budget. When a cap is hit, the API returns 402 Payment Required before running anything — no surprise bills.

​
How metering works

The data plane buffers usage and flushes idempotent batches to the control plane:
  • Idempotent ingestion — each event carries a client_event_id unique per org; retries become no-ops. Metering never blocks a customer response.
  • Atomic aggregation — the raw usage event and its per-org/kind/period roll-up commit in the same transaction, so there’s no divergence window.
  • Exact-integer money — pricing is stored in micro-cents-per-token, with distinct Micros and Cents types so a unit mix-up is a TypeError, not a silent billing error. Conversions round up — the platform never under-bills.

​
Budgets and caps

OrganizationBudget caps consumption across input tokens, output tokens, total tokens, and cost (cents). Caps can be set per org, with optional per-key sub-limits. Budget enforcement gates on two things:
  1. Subscription status — anything but trialing/active blocks consumption.
  2. Caps — any configured limit being exceeded blocks consumption.
When a cap is crossed, the control plane marks budget_ok: false at key validation, and the data plane returns: 
HTTP/1.1 402 Payment Required
{ "error": "budget_exhausted", "reason": "monthly token cap reached" }

# 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": "..." }
Because budget status is part of the cached Principal and the control plane push-invalidates the cache when a cap is crossed, enforcement is near-real- time with a bounded staleness window.

​
Reading current usage

import { Karta } from "@karta/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

karta usage     # via @karta/cli — current period totals + budget

​
No-billing mode

With Stripe unconfigured, everyone stays on the free plan, the billing UI shows a friendly banner, and the app is fully usable without payments wired. Budgets still enforce; only the paid tiers are inert.

API keys

Per-key sub-limits and scopes.

Webhooks

Get notified on budget thresholds and billing events.