Pricing & plans

The commercial page is at lobstack.ai/pricing, and both pages read the same plan catalogue, so the numbers cannot drift apart. This page is about the mechanics behind them: what the allowance counts, what the ceiling does to routing, and what the metered dollar figure on each response is and is not.

A plan used to include a count of messages. A message is not a unit of cost — the same word covered a forty-token ping and a two-hundred-thousand-token context — so an allowance denominated in messages bounded nothing. A plan now includes dollars of model spend, priced at the same per-token rates every response reports. Annual billing takes 20% off; the allowance stays monthly and resets monthly.

Paid plans can also add their own provider keys in Settings › Provider keys. A call that runs on one of your keys is metered and receipted, but it is not marked up and does not spend the allowance. The BYOK plan, metered on requests, is no longer sold.

Top-up packs of $10, $50, $200 add allowance mid-period at the same rate and do not change the plan. They are bought from Console → Usage, and only on a plan that sells them: Free cannot top up, because the wall is what makes the case for paying.

Subscriptions and top-ups both run through Stripe Checkout against configured Price IDs, a pack resolving to its own Price by size rather than by position so reordering the list cannot charge the wrong amount. Both paths require STRIPE_SECRET_KEY in the environment, and without it the checkout routes throw rather than degrade.

Free gets $1 of credit every week: each Monday it tops back up to $1, and unused credit doesn't carry over. The week starts Monday 00:00 UTC. Each top-up is a new credit that expires the next Monday, so there is never more than one week’s worth. It goes to organizations whose owner has signed in with a confirmed email, one per person, and it is counted in x-lobstack-quota-allowance-usd; what is left of it this week is in x-lobstack-quota-weekly-credit-usd. Paid plans do not get it.

An organization that connects the Lobstack app for the first time gets $5 of model spend for 30 days. It is drawn only after the month’s plan allowance is used up. Credit that runs out soonest is spent first, so the weekly credit usually goes before the welcome credit. It is counted in x-lobstack-quota-allowance-usd (what is left of it is in x-lobstack-quota-credit-usd), and whatever is unused when it expires simply lapses. One per organization, and one per person.

Logs, Usage, /api/v1/usage and /api/v1/requests show request-by-request history for 7 days on Free, 90 days on Developer, 1 year on Agency, unlimited on Scale. A period that reaches further back starts where your plan's history does, and the response says so in history.limited; the Console greys out the periods your plan does not include.

Rows older than your plan's history plus 30 days may be deleted, and nothing in the current billing month ever is — so upgrading within a month brings the older history back. Monthly totals per client and model are kept either way, and a client statement for any past month still adds up.

The plan ceiling is the highest tier that "auto" may reach. Free is capped at standard; every paid plan reaches flagship. Paid plans differ in allowance, seats and the organisational features, not in which models they can call.

The cap on Free is a cost control that works in the account holder's favour. One long flagship request can spend the whole $1 weekly credit by itself; capped at standard it runs to hundreds of calls.

A hard prompt against the cap does not fail and does not silently cost more. It is served by the best model under the ceiling and x-lobstack-tier comes back naming that tier, so you can see the cap acting rather than infer it from a worse answer.

Naming a model lowers the ceiling too. Asking for a standard model on a plan that reaches flagship caps that request at standard; the effective ceiling is always the lower of the two.

You can watch the router decide without spending a token on the routing preview. Its plan_tier parameter still takes the legacy tier names rather than the plan ids above: starter reproduces a standard ceiling, and pro, performance and enterprise reproduce flagship. Anything else falls back to pro, so a preview sent "free" today answers as though it were a flagship-ceiling plan.

Three meters, because three different things have been sold. Every response names the one that applied in x-lobstack-quota-meter.

The allowance is enforced for every credential. Legacy agent credentials were exempt until 2026-09-28, while the machines they belonged to still ran; none do now.

A spend meter emits dollar headers and no request counters. A zero in x-lobstack-quota-limit would be read as "no allowance" by a client that cannot tell which meter it is on, so the counters are absent rather than zero.

Only requests that returned below 400 count against an org key's request allowance. A provider outage on our side does not consume your quota. The same rule holds on a spend meter: an error row accrues no spend.

An exhausted allowance is a 402 of class quota, and the message is written in the unit the customer actually bought. retry-after carries the seconds until the period resets, which on a monthly allowance is usually days rather than seconds.

Calls to providers you hold your own key for are the exception: they spend no allowance, so they still go through, and auto routes only among those providers.

Quoting requests to somebody who bought dollars is a support ticket, and quoting dollars to a legacy subscriber who bought messages is a broken promise, so the message names the meter it is refusing on. Errors & retries has the rest of the taxonomy.

Independently of the allowance, every request is priced. The catalog holds a per-million input price and a per-million output price for each model key, verified against each provider's own pricing page on 2026-09-08, and the ledger row freezes the prices that were in force when the request ran.

A request has two costs and they are not the same number. The catalog holds the provider's list price, which is what the tokens cost us. The Lobstack rate is that figure times 1.25, and it is what is debited from a spend allowance and reported on the receipt. Each tier's lead model:

The multiplier applies to managed traffic only. On a call that ran on your own provider key (byok) and in direct mode you have already paid your provider, so the row carries the provider figure in both columns and is marked not billable. What we paid is recorded on the ledger row as provider_cost_usd and never leaves the server: it is in no header, no stream frame and no API response.

Four DeepSeek entries carry priceUnverified: DeepSeek publishes list prices in CNY and its English pricing page has been serving the wrong document, so those USD figures are inherited and flagged rather than converted. A model missing from the catalog entirely is priced as null and the response says x-lobstack-priced: false. It is never recorded as free.

The full catalog, with every price and provider, is on Models & providers, and GET /api/gateway/v1/models returns the same figures as JSON.

A spend allowance is consumed by the dollar figure on each ledger row, and running out of allowance is what a 402 means. It is not a separate line billed on top of the subscription: the subscription and any top-ups you bought are the charges, and the metering is the record of what they were spent on. Legacy agent billing works differently again, with per-message overage rates that run from $0.01 to $0.05 depending on the model, and a message-credit top-up consumed once the monthly allowance is gone.

If you need an authoritative figure for what you owe, read your Stripe invoices, not this metering. If you need to know where your spend went and which key or model caused it, read the metering, because the invoice will never tell you that.

The two can disagree where the metering pre-dates its own columns. A row written before 20260910_spend_metering.sql carries a customer cost and no margin columns, and a row older than the priced ledger carries no cost at all. Nothing backfills either, because the prices and the plan in force at the time are not recoverable, so those gaps stay visible as gaps rather than filled in with a number nobody can reconstruct.

A dollar saving is the difference between what a baseline model would have charged for these exact token counts and what you were charged. When you named a model, that model is the baseline, baseline_reason reads named, and the comparison needs no explanation.

On "auto" there is no model you asked for. The baseline is then the most expensive managed model your plan may reach and baseline_reason reads plan_ceiling. That is a real comparison — it is what you would have paid had you asked for the best one — and it is not the same claim as a saving against a model you actually named. It is also the most favourable comparison available to us, which is why it is labelled rather than merged into one number. A client that renders the figure without the reason is reporting a saving against a model its user never chose.

On a plan that carries the credit, 50% of a verified saving is added back to that period's allowance. Verified means all of: the plan credits savings and meters spend, the request ran on our provider key, the row is not an error row, both models priced, and the baseline is strictly above what was actually charged. Fail any one and the credit is zero.

Routing does not always find something cheaper. On the calls where it does not there is no saving and no credit, and nothing here promises a saving of any particular size — the credit is a share of whatever is measured, which is sometimes nothing.

The percentage in x-lobstack-savings-pct is something else: a heuristic from tier cost multipliers, present on every response. Do not add the two up or treat one as a rounded version of the other. The full rule set is on Metering & cost.