Billing & Usage

Billing is part of the API. A project sits on a tier with included quotas; beyond those quotas, usage either accrues overage or is throttled at a ceiling you set. You can read live usage and headroom, set or remove the spend ceiling, and start an upgrade — all programmatically, so an agent can self-throttle or escalate to a human before running a data-heavy workload.

Billing routes mount under /v1/admin/projects/:projectId/billing/* and require developer credentials (a PAT or console session). Server keys (amb_*_sk_*) are rejected with 403 BILLING_REQUIRES_DEVELOPER_AUTH — billing is an owner action, not a runtime one.

Status

GET .../billing/status returns the current tier, per-meter usage and cost, the billing period and when it resets, projected overage, the spend ceiling and how much of it is consumed, the live enforcement state, and — importantly for agents — human_action_required, a single field telling you whether it's safe to proceed unattended.

curl 'https://api.amba.dev/v1/admin/projects/$PROJECT_ID/billing/status' \
  -H 'Authorization: Bearer $AMBA_PAT'

{
  "data": {
    "tier": "pro",
    "headroom": {
      "mau": { "used": 4200, "included": 25000, "pct": 0.168 },
      "engagement_events": { "used": 120000, "included": 250000, "pct": 0.48 },
      "telemetry_events": { "used": 0, "included": null, "pct": null },
      "push": { "used": 3000, "included": 50000, "pct": 0.06 },
      "db_storage_mb": { "used": 210, "included": 1024, "pct": 0.205 }
    },
    "projected_overage_usd_this_month": 0,
    "recorded_overage_usd_this_period": 0,
    "billed_overage_usd_this_period": 0,
    "metered_billing_live": false,
    "ceiling_usd": null,
    "mode": "throttle",
    "paused_at": null,
    "subscription_status": "active",
    "current_period_end": "2026-06-01T00:00:00.000Z",
    "human_action_required": "none",
    "period": { "start": "2026-05-01", "resets_at": "2026-06-01T00:00:00.000Z" },
    "usage_cost_by_meter": {
      "mau": { "used": 4200, "included_quota": 25000, "overage_units": 0, "cost_usd": 0 },
      "engagement_events": {
        "used": 120000,
        "included_quota": 250000,
        "overage_units": 0,
        "cost_usd": 0
      },
      "telemetry_events": { "used": 0, "included_quota": null, "overage_units": 0, "cost_usd": 0 },
      "push": { "used": 3000, "included_quota": 50000, "overage_units": 0, "cost_usd": 0 },
      "db_storage_mb": { "used": 210, "included_quota": 1024, "overage_units": 0, "cost_usd": 0 },
      "media_storage_mb": { "used": 0, "included_quota": 1024, "overage_units": 0, "cost_usd": 0 },
      "app_mcp_tool_calls": {
        "used": 1400,
        "included_quota": null,
        "overage_units": 1400,
        "cost_usd": 0.07
      }
    },
    "ceiling_pct_consumed": null,
    "projected_end_of_period_overage_usd": 0.07,
    "enforcement": { "read_only": false, "reason": null, "over_quota_meters": [] }
  }
}

enforcement is the live verdict the API itself acts on: when read_only is true, metered write operations return 402 until the period resets or the ceiling changes (see Spend ceiling); over_quota_meters lists meters whose included quota is already consumed — writes on those meters are refused on throttle mode (402 TIER_QUOTA_EXCEEDED, except mau, where new-user signups keep their long-standing 429 MAU_CAP_REACHED shape).

Three overage figures, deliberately distinct so the status never overstates what you owe:

human_action_required is one of:

An agent should call this before provisioning new features or pushing large workloads.

Spend ceiling

Cap the monthly bill with PUT .../billing/ceiling. When the current period's overage cost reaches the ceiling, the project degrades to read-only mode: metered write operations — tracking events, inserting or updating collection rows, media uploads, push sends, new user signups — return 402 SPEND_CEILING_REACHED with a machine-readable payload, while reads (and deletes, which shrink usage) keep working. Pass ceiling_usd: null to remove the cap (linear overage, no limit).

{
  "error": {
    "code": "SPEND_CEILING_REACHED",
    "message": "This project reached its $250 spend ceiling for the current billing period…",
    "details": {
      "read_only": true,
      "reason": "ceiling",
      "meter": "engagement_events",
      "current_usage_usd": 250.4,
      "ceiling_usd": 250,
      "ceiling_pct_consumed": 1.0016,
      "resets_at": "2026-07-01T00:00:00.000Z",
      "billing_url": "https://app.amba.dev/billing"
    }
  }
}

The same contract applies to tier quotas on throttle mode (the default): once a meter's included quota is consumed, writes on that meter return 402 TIER_QUOTA_EXCEEDED with the identical payload shape (reason: "quota"). New-user signups keep their long-standing 429 MAU_CAP_REACHED shape at the MAU quota. Enforcement takes effect within seconds of a ceiling change and resets automatically when the billing period rolls.

So you're never surprised by either the bill or the read-only flip, two control-plane webhook events fire as the ceiling fills — subscribe with amba_control_webhooks_create (or billing.*):

curl -X PUT 'https://api.amba.dev/v1/admin/projects/$PROJECT_ID/billing/ceiling' \
  -H 'Authorization: Bearer $AMBA_PAT' \
  -H 'Content-Type: application/json' \
  -d '{ "ceiling_usd": 250 }'

{ "data": { "ceiling_usd": 250 } }

ceiling_usd must be a finite number between 0 and 100000, or null.

Tiers

The tier catalog (names, prices, included quotas, overage rates) is available offline through the amba_billing_tiers MCP tool, so an agent can reason about upgrades without a network call. It mirrors the pricing page at amba.dev. The shipped tiers are free, pro, scale, and enterprise.

Every tier includes every capability. Tiers differ by quota, not by which features you can use — collections, functions, push, gamification, economy, social, AI, and the rest are all available on every tier, including free. The only feature gates are the quotas in the table below and a couple of free-tier operational limits.

Beyond the included quotas, usage on a paid tier accrues linear overage (unless you set a spend ceiling):

Telemetry events — emitted via Amba.track(name, props, { telemetry: true }) — are billed separately and far cheaper than engagement events because they don't fan out to segments, workflows, or push. Use them for high-volume analytics signals you don't need to drive engagement off.

Agent tool calls — tools/call requests against your project's own app MCP — are priced like engagement events. Like telemetry, they have no included quota; every successful call meters.

How overage is collected

When a project's spend mode is overage_bill (rather than throttle), requests past your included quotas are allowed through and the overage is tallied into a per-period usage ledger. A daily reconciliation totals each metered axis for the current billing period and adds the billable amount to your upcoming invoice — so overage rolls into your next invoice rather than being charged per-request.

Upgrade & manage

Two routes return hosted URLs you redirect the human to — these flows need a browser, so they're surfaced to a person rather than driven by an agent:

POST .../checkout takes { tier: "pro" | "scale", interval: "month" | "year" } and returns a checkout url. If the project already has an active subscription, it returns 409 SUBSCRIPTION_EXISTS — use the portal to change plan instead. POST .../portal opens the billing portal so the owner can update their card, change plan, or download invoices.

MCP tools