Money, Limits and Members
The wallet
Your account pays for runs from a prepaid wallet. Nothing runs until the wallet holds money: each call a run makes is reserved against it before the call is made. What each model and each search, document and page costs is on Pricing.
An owner adds money on Wallet & budgets: press an amount, such as Add $20.00, and pay with Stripe. The same page shows, for each loop, what it has spent this month, what is held for runs in flight, and its monthly cap, and what each user has spent against the per-user cap. A member of your account is named; any other user is named by kind and id: a signed-out visitor by the end of the id the platform gave them, and a signed-in user or an API user by the id your own site or server sent. A loop that is no longer in your library reads A removed loop, and an archived one keeps its name with (archived).
Four budgets
Every run is held to four limits, set in the loop’s record and checked before every call:
| Budget | Where you set it |
|---|---|
| The account’s wallet | The money you add. |
| A monthly cap for the loop | budgets.monthly_micros |
| A cap per user | budgets.per_user_micros |
| A budget per run | budgets.per_run_micros |
Amounts are in millionths of a US dollar, so 50000 is five cents. A run’s budget must not be
more than the per-user cap, and the per-user cap must not be more than the monthly cap: publish
refuses a record that breaks the order and names it.
A scheduled automation and an email delivery are paid from the wallet alone. Each firing of an automation costs a fixed amount and is held before it runs: if the wallet cannot cover it, the run stops before any step, and its row on Automations says the wallet could not cover it. Each email a loop sends costs a fixed amount too; an email is sent even when the wallet cannot cover it. Neither counts toward a loop’s monthly cap or a per-user cap. A webhook delivery costs nothing.
A test case counts toward the wallet, the loop’s monthly cap and its own run budget, never toward a per-user cap. It is you checking a version before you publish it, not a user of the loop, so publishing a version with several test cases does not use up your own per-user cap.
A run that meets a limit still starts, then ends with the ending over_budget and the message you
wrote for it. Your server reads that ending; there is no payment error code. Your users never
see a budget, a price or a model, only the conversation.
The last line of every run
end_messages in the record holds the user’s last line for each way a run can end:
completed, over_budget, lapsed, check_failed, stopped, and otherwise for every ending
you did not name. otherwise is required, so a person never meets an ending as silence. The
platform never writes a closing line for you.
A run whose same step keeps failing in the same way stops rather than keep paying. With one of
your users in the chat, it ends at once with your otherwise line, because nobody from your
account is there to decide; in your own run on the console it asks you first whether it may
try again.
Limits on who may start runs
Each loop’s identity.limits bound the people who reach it:
per_ip— run starts, new-visitor sign-ins and searches from one network address in a window, for example30/1m. They share one count, so a new visitor’s first conversation spends two:per_ip: 10/1hlets about five new visitors start one conversation each from one address in an hour.per_subject_runs— runs by one user in a window, for example5/1d.concurrent_runs— optional: how many runs started through the run API may be running or waiting at once.
When one of these refuses, your user reads when to come back in words, for example “You have
started as many conversations here as are allowed for now. You can try again in about 4 hours.”
The answer is a 429, and its Retry-After header carries the exact seconds for programs.
Each route of the API also has its own rate limit. A refused request answers 429 with a
sentence that names the limit, and a Retry-After header with the seconds to wait.
Members
Members lists the people who can sign in to the account, and the role each holds. A member signs in with Google; your users never have an account here.
| Role | What it may do |
|---|---|
| Owner | Everything a member does, and also: the API keys and secrets, adding money, archiving and reopening a loop, invitations, roles and the audit log. |
| Member | Build, test and publish loops, operate runs, and decide the steps that wait on the account. |
An owner invites someone: enter their email address and a role, and press Send invitation. They open the link in the email and sign in with Google as that address to join. An owner can make a member an owner or an owner a member, and remove a member; anyone can leave. The account always keeps at least one owner.
Owners also see the account’s Audit log, a tab of Members: the changes members made, newest first, and who made each one.