Pricing and limits

What each Charming plan costs and includes, plus size caps, rate limits, and token lifetimes for Charming apps.

The first anonymous app needs no signup and lasts 7 days. Claim it to keep it. There is no enforced app cap per account today. The OpenAPI specification is the machine-readable source for current limits.

Tiers at a glance

See Authentication for token scope, claim, recovery, and revocation.

Plans

A claimed app belongs to an owner, an account or a team, and the owner’s plan sets the numbers below. Every owner starts on Free. Pro is for one person; Business is for a team and is billed per seat. The pricing page compares the plans side by side.

A per-seat number is multiplied by the seats a team is billed for, and a Business team is always billed for at least three. Enterprise plans set their numbers per contract. The owner’s billing page, in Account settings or the team’s settings, is where a plan is bought or changed.

Webhook body kept per delivery sizes a record, not a delivery. A Webhook’s delivery record keeps that much of the request body and that much of the response body, and drops the rest. The op still gets the whole request, and the sender the whole response.

A capability a plan does not include refuses with plan_required. Adding a Routine or a Webhook past the plan’s cap refuses with routine_limit_exceeded or webhook_limit_exceeded, and restoring a version outside its saved versions refuses with version_limit_exceeded. See Plan refusals.

Per-account limits

Listing only returns the caller’s apps (owned + collaborator); paging uses an opaque cursor.

The Routines and Webhooks caps count across all the apps one owner holds, whether that owner is you or a team. An unclaimed app has no owner, so only the per-app cap bounds it.

Per-app limits

Both env.storage caps apply. Delete or shrink a key to make room. Everyone using an app shares one store, the owner’s; anonymous visitors on a custom domain get their own.

Plan refusals

Some limits belong to the owner’s plan rather than to the app. They all refuse with one shape, so a caller reads the same fields wherever it meets one.

upgradeUrl is omitted when the owner has no handle and therefore no settings page of their own, so treat it as optional. MCP repeats it as an Upgrade: <url> last line in the error text, and the CLI prints it under the message.

A refusal is not a transient failure. Nothing about the request was wrong, so retrying it returns the same answer until the plan changes or the count drops.

Restoring a version older than the plan’s History window is refused with version_limit_exceeded. Inside the window, a revision that is missing or cannot be rebuilt stays version_not_restorable, which upgrading does not fix. Outside it the plan answers first, so a revision that is both out of reach and unbuildable reads as a plan refusal.

Usage allowances

Runs and storage count across every app an owner holds. A team’s apps count toward the team. Each plan’s allowance is in Plans. A month of Runs is the last 30 days, rolling. Activity history is what /activity and get_app’s recent issues can read.

A Run is an app load, an operation, or a Routine firing. Storage includes what visitors save in public apps. The Usage page, for the account and for each app, shows Runs by kind over 7 days, 30 days, or 12 months; ranges past the plan are locked.

At 80% the dashboard shows a notice. At 100% the owner, or a team’s admins, get one email, at most once every 30 days.

Storage past the allowance does not stop an app from saving. The one write it refuses is copying an app with its data: a copy whose data would put the caller over their allowance fails with storage_limit_exceeded and creates nothing.

Activity past the window is hidden, not deleted, and comes back on upgrade. Both activity endpoints return retention: the window in hours, the since cutoff used, and truncated, true when the window set the cutoff.

ESM build limits

Selected authenticated authors can use the ESM contract. It adds a 64 KiB combined module/UI source cap, 256 KiB styles cap, and 2 MiB compiled output cap per target. The build queue admits 16 pending operations overall and 3 per author, with 2 concurrent builds overall and 1 per author. Queue and attempt deadlines are 10 minutes each, within a 20-minute operation lifetime and at most 2 automatic attempts for transient failures.

Terminal input inspection lasts 7 days; operation results, exact locks, and idempotency records last 30 days. Active and historical completed builds remain while app revisions reference them. The public OpenAPI document exposes the current policy as x-charming-app-build-policy.

Network access

Backend requests must use HTTPS and declare each exact origin. Private, loopback, link-local, and cloud-metadata addresses are blocked, including after redirects. Sealed env.fetch responses are capped at 5 MiB. See the build reference for capabilities, permissions, and secret handling.

Rate limits

Token-bucket limiters, in-memory, per process. All windows are 60 seconds.

A Webhook delivery that passes its secret check also takes from a second bucket of 120 a minute per Webhook.

A breach returns 429 with error.kind: "rate_limited" (or "too_many_requests" for asset writes).

Running an app

Every call that runs an app’s own handler is bounded, whichever surface it arrives on: POST /app/{id}/api/{op}, MCP query_app / mutate_app, Routine ticks, and Webhook deliveries all share one budget per app.

A breach returns 429 with error.kind: "app_busy". error.limit names which bound was hit (concurrent_runs, runs_per_window, or render_token_refresh), and error.execution is always not_started, so the call never reached the handler and retrying it is safe. The rolling-window breach also carries error.retry_after_seconds and a Retry-After header; the in-flight breach carries neither, because capacity frees when a run finishes rather than at a knowable time.

render_token_refresh is the page render asking for a new render-token secret. Two bounds hold it in a 60-second window: 10 per app per client IP, and 60 per app across every address. error.observed and error.allowed name whichever one refused, so back off against those numbers rather than assuming the wider bound. The per-(app, IP) one is met first in practice, and on a deployment that does not trust a proxy header every caller resolves to the same address, which puts all of them in one 10-rotation bucket.

Callers who are not members

An operation whose route declares callers (see Let visitors call an operation) has extra bounds for callers who are not members of the App. Members are never held to them.

The last two are shares of the App’s own bounds above, so callers who are not members can never fill them and members always keep the rest. A non-member who arrives once the App has already reached one of its own bounds is refused the same way, as visitor_rate_limited, with error.limit naming the App’s own bound (concurrent_runs or runs_per_window) and its number; only a call refused before its caller is identified answers app_busy.

A breach returns 429 with error.kind: "visitor_rate_limited". error.limit names the bound (visitor_per_address, visitor_per_account, visitor_concurrent_runs, or visitor_runs_per_window), and error.execution is not_started, so retrying is safe. Every bound except the in-flight one also carries error.retry_after_seconds and a Retry-After header. A refused call is not a Run, does not count against the owner’s plan, and never moves the App down the refusal ladder. Every call a caller makes spends from their own bucket, including one the non-member shares then refuse, so retrying against a full share also runs down the caller’s 30. The activity timeline shows refused calls as one visitor_calls_refused row per 10-second window, with count and limit.

When the host itself is at capacity

The server holds a fixed pool of database connections, split so the health endpoint answers while app traffic saturates the rest. A call that cannot get a connection within one second returns 503 with error.kind: "service_busy" and Retry-After: 1. The refusal lands on one statement rather than on the whole call, so a call refused partway through may already have written part of its work. Repeat a read freely; after a write, read the result back before retrying.

This is not your app’s ceiling: app_busy says this app is doing too much, service_busy says the server is. Calls presenting a render token or no credential are refused before calls presenting a user or app token, so a signed-in owner keeps working while anonymous traffic sheds.

An app already at a ceiling is refused at the edge of the request, before its caller’s token is read. A caller holding no credential sees the same 429, and the refusal never spends the app’s budget: a slot is only taken by a call that passed authorization, so nobody can exhaust an app by naming its id.

Refusals are summarized rather than recorded one by one. The app’s activity timeline gets one api_proxy_result row per surface per 10-second window, carrying count (how many calls it stands for), limit (which ceiling refused them), and the first and last timestamps of the window.

An app that trips these is usually looping rather than popular. The most common cause is a refresh handler that triggers the change it is listening for.

Ignoring the wait

Every app_busy body carries error.rung, which says how hard the refusal is. A repeat from the same credential moves the app down a rung when it arrives inside the wait the ladder has already issued: the rolling-window bound’s own Retry-After, or, once a climb has minted one at parked or closed, that minted wait — whichever bound this particular refusal happens to name. Before anything is minted, the in-flight bound’s own first climb has no wait to arrive inside, so a repeat counts there when it lands within one second of the last refusal, at least 50 ms after it. A quiet 60 seconds moves the app back up one rung.

Only a call that passed authorization can move an app down a rung, and only when the same credential comes back inside the wait; an unauthenticated flood against an app id cannot park its owner’s app. A user token, an app token, and a visitor- or user-bound render token each key the ladder narrowly enough that two of those refused a second apart have ignored nothing between them. Two credentials are shared: an anonymous caller keys on its egress IP, one bucket for every anonymous request behind it (or a single bucket for all of them when the deployment has no trusted proxy in front), and the opaque render token minted for a public page is scoped to the app rather than to a reader, so every visitor to that page shares one key. A self-describing render token narrows that shared key to the reader who holds it.

Rate-limit response headers

Every rate-limited route emits the draft-IETF RateLimit-* headers (plus their legacy X-RateLimit-* aliases for older agent tooling) on both success and 429 responses so a client can project headroom without busy-polling:

The numbers reflect the most-restrictive bucket among all that gate the request (e.g. (app, IP) vs (app) for diag/feedback/load-error). The Retry-After value lets generic HTTP clients back off without parsing the body.

Token TTLs

chrm_user_* token revocation is immediate (DELETE /api/token/<id>), including for the token that makes the call. The authentication reference has the list call, the browser path, and the rotation order.

What is NOT metered today

Beyond the usage allowances:

• App create / update calls have no per-minute write limit on POST /app or PUT /app/{id}. ESM builds have the queue and concurrency caps above.
• App reads (GET /app/{id}, GET /app/{id}/source, GET /app/{id}/describe, GET /app/{id}/agent.json)

The route limits cover paths an anonymous caller can hit: diagnostics, feedback, asset writes, pairing, and Webhook deliveries. Authenticated PUT and PATCH writes use the bearer token instead of a per-minute counter.

When numbers change

Fetch the OpenAPI specification for the live values.