Empirical Tokens.

What they are

Empirical Tokens are a monthly allowance. Your plan includes a fixed number each month. They reset at the start of the month, shown in your own time zone, and do not carry over, and they cannot be bought separately. The reset happens at the same moment for everyone, so in your own time zone the date can be the last day of the month before. They are not the model tokens an AI provider counts: a feature costs a fixed number of Empirical Tokens, whatever the model used.

How many your plan includes

Each paid plan includes Empirical Tokens every month. The free plan includes none, because the features that use them are part of the paid plans.

• Starter: 200 a month.
• Builder: 1,000 a month.
• Architect: 2,400 a month.
• Your trial includes 200 Empirical Tokens. Your plan's full monthly amount starts once your first payment goes through.
• Switching plans during your free trial ends the trial and charges the new plan right away. We show you the exact amount first. Your Empirical Tokens go up to the new plan's amount, minus what you have already used, once the payment goes through.

What uses them

Only a few features use Empirical Tokens, and you always see the cost before anything starts.

• Each priced feature shows its cost before you start, and nothing starts until you agree (for example, building a writing voice is currently 200 Empirical Tokens, used when the interview starts). Resuming the same interview uses none. Stopping partway does not return them, and your answers stay saved so you can come back and finish. Unfinished setups are deleted after about two weeks, and the Empirical Tokens used at the start are not returned then.
• A blueprint marked as AI-heavy shows its cost before install. Most blueprints use none.
• When Empirical Tokens apply to your account, each interview includes a limited amount of AI work. If an interview uses all of it, you can still install the current draft if it is up to date, or start a new interview.

Check what is left

Your balance is on the Subscription page in the portal, with a list of what was used this month. From the CLI run empirical usage; in a connected assistant, ask it to call get_user and read empiricalTokens.

• The balance only appears once Empirical Tokens apply to your account. Until then the portal, empirical usage and get_user show no Empirical Tokens line.

empirical usage
empirical usage --json

From the CLI

Three commands touch Empirical Tokens. empirical usage prints your memory use, this month's blueprint installs and, when Empirical Tokens apply to your account, one line such as Empirical Tokens: 1,000 of 1,000 left this month. Resets October 31 at 8:00 PM EDT. empirical usage --json prints the same facts as JSON and carries empiricalTokenUsage only when they apply to your account. empirical whoami prints your account as JSON and, when they apply, an empiricalTokens line with the same text. empirical setup run shows the cost of a priced setup and starts nothing until you agree.

• At a terminal, empirical setup run shows the cost and asks Start? (y/N). Answer y to start. Any other answer, or no answer, starts nothing, spends nothing, and the command exits with an error.
• In a script or any run without a terminal, the command never accepts a cost for you. It prints the cost, starts nothing and exits with an error. Add --accept-cost only when the person running it has already agreed.
• If an attempt is refused and its Empirical Tokens were returned, the CLI says so once: Your Empirical Tokens for this attempt were returned.

empirical setup run setup_writing_voice
empirical setup run setup_writing_voice --accept-cost

When you run out

A feature that needs more Empirical Tokens than you have left does not start and nothing is charged. The message says when they reset and which plan includes more. Assistants see the code PLAN_LIMIT_EMPIRICAL_TOKENS_REACHED and are told not to retry until the reset or an upgrade.

• The portal also shows a banner when most of this month's Empirical Tokens are used, and again when they are all used.
• Empirical Tokens never block saving or searching memories.

Errors

These are the codes you can meet around Empirical Tokens, with the HTTP status the API answers with. In an assistant, the same code arrives with a plain message.

• PLAN_LIMIT_EMPIRICAL_TOKENS_REACHED (403): not enough Empirical Tokens left. Nothing was started or charged. Wait for the reset at the start of the month, shown in your own time zone, or move to a plan that includes more.
• EMPIRICAL_TOKENS_UNAVAILABLE (503): Empirical could not check your Empirical Tokens, so nothing was started or charged. Try again in a minute.
• EMPIRICAL_TOKENS_ATTEMPT_CLOSED (409): this attempt was not charged and cannot be charged now. Start it again as a new interview or install; nothing was taken. Do not retry the same attempt.
• EMPIRICAL_TOKEN_KEY_OWNER_MISMATCH (403): the interview or install belongs to another account, so nothing was started or charged. Use one that belongs to your account.
• GUIDED_SETUP_VOICE_BUSY (409): the interview is still handling your last answer. Wait a moment and send it again; it clears on its own.
• GUIDED_SETUP_VOICE_SESSION_LIMIT (409): the interview has used all the AI work one interview includes, or its Empirical Tokens were returned. Install the current draft if it is up to date, or start a new interview.
• PLAN_CHANGE_CONFIRMATION_REQUIRED (409): the charge for a plan change moved since you were shown it, or a change must be confirmed first. Read the new amount shown and confirm it again. Nothing was charged.
• PLAN_CHANGE_PAYMENT_FAILED (402): your card was declined while a plan change was ending your free trial, so nothing changed and you are still on your trial. Update your card, then try again. A declined upgrade on a plan you already pay for is not an error: the answer is 200 with pendingPayment set to true, nothing changed, and you stay on your current plan.
• PLAN_CHANGE_PREVIEW_UNAVAILABLE (502): Empirical could not work out the charge for the change just now, so the change was not offered. Try again in a minute.
• NO_LIVE_SUBSCRIPTION (400): there is no live subscription to change. Start a new subscription from the pricing page instead.
• PLAN_CHANGE_FAILED (502): Empirical could not confirm whether your plan changed. Open the Subscription page and check it in a minute before trying again.
• TRIAL_END_FAILED (502): Empirical could not confirm whether starting your plan now went through. Open the Subscription page and check it in a minute before trying again.
• TRIAL_END_IN_PROGRESS (409): a plan change that ends your trial is already being processed. Check the Subscription page in a minute.

Cost previews and returned Empirical Tokens: A priced start does not begin on the first call. The start call (REST, MCP and the CLI) answers with status cost_confirmation_required and the cost. Calling again with acceptEmpiricalTokenCost true starts it, and only after the person agrees. Refusals that return the Empirical Tokens of that attempt carry details.refunded set to true.

Limits

Empirical Tokens are per account, not per workspace. An assistant can only start a priced feature after it shows you the cost and you agree; it is told never to accept the cost for you.