Developers/API Reference/Billing & Usage API

Billing & Usage API

Read-only endpoints for pulling your domain's current-period usage, plan catalog, prepaid Power-credit wallet, and add-on catalog into your own dashboards or alerts.

Overview

The Billing & Usage API lets you read what your domain has consumed and what it's entitled to, without opening the dashboard at app.supero.dev. It's built for teams that want to mirror usage into their own admin panel, trigger an internal alert before a plan limit is hit, or reconcile Power-credit spend in their own systems. Every endpoint on this page is a GET. Usage is metered automatically by the platform as you call the API, generate apps, run connectors, and deploy — there is no customer-facing endpoint to submit or emit usage events yourself; you only ever read what the platform already recorded. Plan changes, invoices, and payment are managed from the Subscription page in the dashboard, not documented here — see Plans & Billing for what each plan includes.

ℹ️ Scope

Every authenticated read is scoped to the domain in your JWT or API key — there is no domain/tenant query parameter that can point the request at a different workspace. If you pass one anyway it's ignored.

Authentication

Send either an API key or a user's access token. The plan catalog is public; every other endpoint on this page requires the billing:manage permission, which domain_admin holds by default (other roles need it granted explicitly through RBAC).

bash

# API key
curl https://api.supero.dev/api/v1/billing/usage/summary?period_month=2026-07 \
  -H 'X-API-Key: ak_your_key_here'

# User access token
curl https://api.supero.dev/api/v1/billing/usage/summary?period_month=2026-07 \
  -H 'Authorization: Bearer eyJhbGciOi...'

Endpoint	Auth required	Permission
GET /api/v1/billing/plans	No	public
GET /api/v1/billing/usage/summary	Yes	billing:manage
GET /api/v1/billing/credits	Yes	billing:manage
GET /api/v1/billing/credits/packs	Yes	billing:manage
GET /api/v1/billing/credits/transactions	Yes	billing:manage
GET /api/v1/billing/addons	Yes	billing:manage

Usage summary

GET /api/v1/billing/usage/summary returns the current-period usage snapshot for your domain: AI token/cost counters, generation run counts, API request volume, storage gauges, connector activity, and the rolled-up Power total. period_month is required and must match YYYY-MM.

bash

curl 'https://api.supero.dev/api/v1/billing/usage/summary?period_month=2026-07' \
  -H 'Authorization: Bearer eyJhbGciOi...'

json

{
  "domain": "acme-corp",
  "period_month": "2026-07",
  "found": true,
  "ai_input_token_count": 182340,
  "ai_output_token_count": 41200,
  "ai_cache_read_token_count": 9800,
  "ai_cache_write_token_count": 1200,
  "ai_call_count": 214,
  "ai_cost_micros": 3120000,
  "ai_cost_by_model": {},
  "agent_prompt_count": 18,
  "appgen_run_count": 3,
  "schemagen_run_count": 1,
  "testdata_run_count": 2,
  "deploy_run_count": 1,
  "image_fetch_count": 56,
  "api_request_count": 48210,
  "storage_bytes_total": 1073741824,
  "object_count_total": 5321,
  "connector_execution_count": 12,
  "connector_records_count": 8400,
  "connector_run_query_count": 3,
  "compute_workflow_count": 0,
  "cloud_run_hours": 4.5,
  "project_count": 3,
  "tenant_count": 12,
  "server_count": 1,
  "team_member_count": 4,
  "total_cost_micros": 3120000,
  "non_ai_cost_micros": 0,
  "power_units": 8420,
  "power_by_meter": {
    "ai.tokens.input": 1823,
    "connector.execution": 600,
    "deploy.run": 200
  },
  "overage_detected": false,
  "as_of": "2026-07-18T09:00:00Z"
}

AI & generation fields

Field	Type	Description
ai_input_token_count	integer	Prompt/input tokens consumed this period.
ai_output_token_count	integer	Completion/output tokens generated this period.
ai_cache_read_token_count	integer	Prompt-cache read tokens (disjoint from input).
ai_cache_write_token_count	integer	Prompt-cache write/creation tokens.
ai_call_count	integer	Number of AI calls made.
ai_cost_micros	integer	AI spend this period, in micro-USD (divide by 1,000,000 for dollars).
ai_cost_by_model	object	AI cost broken down per configured model identifier.
agent_prompt_count	integer	Native AI agent prompts (one user turn each).
appgen_run_count	integer	Full app-generation runs.
schemagen_run_count	integer	Schema-generation runs.
testdata_run_count	integer	Test-data generation runs.
deploy_run_count	integer	App cloud-deploy runs.
image_fetch_count	integer	External image-provider fetches.

Platform, storage & connector fields

Field	Type	Description
api_request_count	integer	REST API requests this period.
storage_bytes_total	integer or null	Total stored bytes. null means storage hasn't been probed yet for this period — treat it as ‘not yet metered’, not zero.
object_count_total	integer or null	Total stored object count; same null semantics as storage_bytes_total.
connector_execution_count	integer	Connector sync executions.
connector_records_count	integer	Records synced through connectors.
connector_run_query_count	integer	Warehouse connector run_query executions.
compute_workflow_count	integer	Workflow step executions run on your behalf.
cloud_run_hours	float	Cloud-run instance runtime hours.
project_count	integer	Live project count (internal/system projects excluded).
tenant_count	integer	Tenant count under this domain.
server_count	integer	Active server activation count.
team_member_count	integer	Team member seat count.

Cost, Power & meta fields

Field	Type	Description
total_cost_micros	integer	Total billable cost this period, in micro-USD.
non_ai_cost_micros	integer	Billable non-AI cost, in micro-USD.
power_units	integer	Total Power consumed this period — the unified activity/compute capacity your plan grants alongside storage.
power_by_meter	object	Power drill-down: meter key → units drawn, so you can see what's consuming your Power budget.
overage_detected	boolean	Whether this period is over an included allowance.
found	boolean	false when no snapshot exists yet for the period (a brand-new domain, or a period with no activity) — all counters read as their zero/null defaults.
as_of	string (ISO 8601, UTC) or null	When the served snapshot's gauges and sums were last materialized.

⚠️ period_month format

period_month must be exactly YYYY-MM (e.g. 2026-07). A malformed value (2026/07, 2026-7, a full date) returns 400/422 instead of a summary.

Plan catalog

GET /api/v1/billing/plans returns every publicly listed plan tier with its resource limits, sorted by tier level. All six are public: trial, basic, starter, pro, business and enterprise. It's unauthenticated, so you can use it to build your own pricing/comparison page. The sample below is abbreviated to one entry — see Plans & Billing for what each tier includes.

bash

curl https://api.supero.dev/api/v1/billing/plans

json

{
  "success": true,
  "count": 6,
  "plans": [
    {
      "plan_code": "pro",
      "display_name": "Pro",
      "tier_level": 20,
      "monthly_price_cents": 19900,
      "annual_price_cents": 191040,
      "payable_monthly_price_cents": 9950,
      "payable_annual_price_cents": 95520,
      "discount_applied": true,
      "discount": {"active": true, "percent_off": 50.0, "label": "Launch offer", "applies_to": "plan_subscriptions", "duration": "forever"},
      "max_schemas": -1,
      "max_api_requests_monthly": -1,
      "max_storage_bytes": -1,
      "max_team_members": -1,
      "max_projects": 10,
      "features": ["ai_agent", "advanced_rbac"],
      "sdk_languages": ["python", "javascript"],
      "support_level": "priority",
      "trial_days": 14,
      "requires_payment_method": true
    }
  ]
}

Field	Type	Description
plan_code	string	Unique plan identifier, e.g. trial, starter, pro, business, enterprise.
display_name	string	Human-readable plan name.
tier_level	integer	Numeric tier for ordering/comparison; higher is a larger plan.
monthly_price_cents / annual_price_cents	integer	LIST price in cents, before any platform-wide offer. Current prices are on the Billing screen in your dashboard at app.supero.dev/billing — treat any number you cache from this field as subject to change.
payable_monthly_price_cents / payable_annual_price_cents	integer	What you actually pay, net of any active platform-wide offer. Equal to the list price when no offer is running, so you can read this field unconditionally. This is the number to charge against and to show as the price; show the list field struck through beside it.
discount_applied	boolean	True when an offer actually lowered this plan's price. False for free and contact-sales plans even while an offer is running, so you never render "50% off" beside Free.
discount	object	The active offer: percent_off, label, applies_to, duration. Present per plan and once at the top level of the response so a banner can be rendered without inspecting every plan. active is false when no offer is running.
max_schemas	integer	Maximum schemas allowed (-1 = unlimited).
max_api_requests_monthly	integer	Monthly API request cap (-1 = unlimited).
max_storage_bytes	integer	Storage cap in bytes (-1 = unlimited).
max_team_members	integer	Team seat cap (-1 = unlimited).
max_projects	integer	Hard project cap (-1 = unlimited).
features	string[]	Feature flags bundled with the plan, e.g. ai_agent, advanced_rbac.
sdk_languages	string[]	SDK languages available on this plan.
support_level	string	community, email, priority, dedicated, or premium.
trial_days	integer	Free trial length in days.
requires_payment_method	boolean	Whether a payment method is required to start.

💡 AI Agent and RBAC by tier

features is the authoritative signal for what a plan bundles — for example whether the AI Agent or advanced RBAC come included, versus needing the matching add-on. Check for the feature flag rather than hardcoding plan_code comparisons, since bundling can change per tier over time.

Prepaid Power credits

Power is Supero's usage currency — your plan grants a monthly Power allowance (see max_power_units on the plan), and a prepaid credit-pack wallet lets you draw down extra Power beyond that allowance without changing plans. These three endpoints read the wallet balance, the purchasable pack catalog, and the transaction ledger.

Wallet balance

bash

curl https://api.supero.dev/api/v1/billing/credits \
  -H 'Authorization: Bearer eyJhbGciOi...'

json

{
  "domain": "acme-corp",
  "power_balance": 214500,
  "lifetime_purchased": 500000,
  "lifetime_consumed": 285500
}

Purchasable packs

bash

curl https://api.supero.dev/api/v1/billing/credits/packs \
  -H 'Authorization: Bearer eyJhbGciOi...'

pack_id	power_units	label
power_50k	50,000	50K Power
power_250k	250,000	250K Power
power_1m	1,000,000	1M Power

Each pack also carries a price_cents field; current prices are on the Billing screen in your dashboard at app.supero.dev/billing.

Transaction ledger

bash

curl https://api.supero.dev/api/v1/billing/credits/transactions \
  -H 'Authorization: Bearer eyJhbGciOi...'

json

{
  "transactions": [
    {
      "uuid": "5b6a...",
      "txn_type": "purchase",
      "power_units": 250000,
      "balance_after": 214500,
      "pack_id": "power_250k",
      "description": "Power credit pack purchase",
      "created_at": "2026-07-02T14:11:00Z"
    },
    {
      "uuid": "9f21...",
      "txn_type": "consume",
      "power_units": -35500,
      "balance_after": 214500,
      "period_month": "2026-07",
      "description": "Over-allowance settlement",
      "created_at": "2026-07-31T23:59:00Z"
    }
  ]
}

Field	Type	Description
txn_type	string	purchase, consume, refund, grant, or expire.
power_units	integer	Signed Power delta — positive for purchase/grant/refund, negative for consume/expire.
balance_after	integer	Wallet balance immediately after this entry.
amount_cents	integer (optional)	Money paid for a purchase entry; absent for consume/grant entries.
pack_id	string (optional)	Credit pack purchased, if this is a purchase entry.
period_month	string (optional)	For consume entries, the period whose over-allowance this entry settled.
description	string	Human-readable note.
created_at	datetime	When the entry was written.

Add-on catalog

GET /api/v1/billing/addons lists the recurring add-ons you can attach on top of any plan — useful for showing customers or your own ops team what's available and what's already bundled.

bash

curl https://api.supero.dev/api/v1/billing/addons \
  -H 'Authorization: Bearer eyJhbGciOi...'

addon_id	label	unit	Notes
ai_agent	AI Agent	per month	Bundled free on Pro, Business, and Enterprise; a paid add-on on lower tiers. Every plan gets a small free monthly allowance of AI-agent queries before this is needed.
custom_domain	Custom domain	per project / month	The catalog entry offers to serve a project on your own domain with managed SSL. Treat that description as out of date: custom domains are not self-service, purchasing this add-on provisions no DNS and no certificate, and nothing about a deployed app's address changes. Read Custom Domains before you add it. Not bundled on any tier.
multi_tenancy	Multi-tenancy	per 100 tenants / month	Adds tenant capacity for multi-tenant apps; stack units for more. Not bundled on any tier.
rbac	RBAC	per month	Custom roles, granular per-schema permissions, and an audit log. Bundled free on Pro, Business, and Enterprise.

Each entry also carries a price_cents field; current prices are on the Billing screen in your dashboard at app.supero.dev/billing. To check whether a specific domain already has an add-on entitled (bundled by its plan or purchased separately), read its subscription from the dashboard rather than inferring it from this catalog alone.

Errors

Status	Meaning
400 / 422	Malformed request, most commonly an invalid period_month on the usage summary endpoint.
401	Missing or invalid credentials (no Bearer token / API key, or an expired token).
403	Authenticated, but the caller's role/permission set doesn't include billing:manage.
500 / 502 / 504	An unexpected server error or an upstream billing dependency was unreachable/timed out — safe to retry with backoff.

ℹ️ found: false is not an error

A brand-new domain, or a period with zero recorded activity, returns 200 with found:false and every counter at its zero/null default — not an error status.

Next steps

•Authentication — generating and scoping X-API-Key credentials
•Roles & Permissions Reference — the full permission set, including billing:manage
•CRUD Endpoints — the core CRUD and query endpoints
•Managed Integrations & Provider Catalog — wiring managed services that also draw from your Power budget

← PreviousAI Agent API Next →Python SDK

On this page