Plan and usage

Prompt:

Upgrade this app to Standard. How much have we used this month?

Also works:

  • "What does the Pro plan include?"
  • "Why is my app answering 429?"
  • "Move the test app back to Free."

What your tool does

  • Calls list_applications to find the application the prompt mentions, keeps its identifier, and reads its current plan.
  • Reads the platform's cost-review skill, which sets the order: read the usage, then move the plan.
  • Calls read_usage with the application's identifier and reports each measure's month_total against its quota, with its state, for the current UTC month.
  • Calls read_plan_quotas when you ask what a plan includes. Any signed-in credential can read the quotas, so no application on that plan is needed.
  • Calls set_plan with the identifier and the plan, plan: "standard" for the prompt above. It reports the recorded plan, warm_floor, and connection_limit, and the detail sentence.
  • Calls restart_application for each environment the detail lists, so each running copy with a database takes the new connection limit.
  • Asks you which plan to move to when the prompt does not say. The platform assigns no default plan.
  • Asks for no browser approval, because set_plan and restart_application are reversible-tier actions.
  • Writes nothing into your project, and changes no plan unless you asked for it.

Before your AI starts

This section is for your AI tool: what it checks and gathers before it begins. You don't need to do these steps yourself.

  • A connected, signed-in tool (Connect your tool).
  • The application's identifier, which list_applications returns.
  • For a move to free, no other live Free application on the account.
  • During the beta, for a move to standard or pro, no other live application on that plan in the account.

Steps

1. Choose a plan

Each application has its own plan: free, standard, or pro. Your tool asks you which plan when it calls create_application (Deploy an application), and set_plan changes it later. One application per account can be on Free, and Free needs no card.

Free costs nothing. An application on Standard or Pro is billed from its creation on that plan, or from the set_plan that moves it there. Whether it has one environment or two, and whether it has deployed yet, changes nothing.

During the beta, no plan is charged, and an account can also have one live application on Standard and one on Pro. Deleting an application frees its place on its plan, and these two limits end with the beta.

The pricing page lists each plan's price and included quantities. read_plan_quotas returns the same quantities to your tool. Called with no argument, it returns rows for all three plans:

  • ten rows per plan for the quantities the platform enforces, push-messages-capacity among them, then one row for each other value the plan sets: six on Free, five on Standard and Pro;
  • each row's quantity in base units, or null where the quantity is unset. The response's detail gives each unit: schedule-minimum-interval in minutes, free-idle-stop in seconds, and development-halt-after-days in days. stored-data-capacity, data-transfer-capacity, log-retained-capacity, and egress-bytes-per-day are in bytes, gemini-flash-allowance in token units, and every other entry is a count;
  • each row's set_at time and set_by, who set it.

Any signed-in credential can call it, a token bound to one application included.

To read fewer rows, name plan (free, standard, or pro), measure (an entry's name, such as schedule-count-limit), or both. plan returns that plan's rows, and measure returns that entry's row on each plan that sets it. Both together return at most one row. Where the plan does not set that entry, quotas is empty and detail says why. Over HTTP, a value outside these lists is refused invalid_request.

Every plan can have a development environment. create_environment turns it on, and the rows whose names begin with development- give its limits.

2. Change the plan

set_plan takes the application identifier and a plan of free, standard, or pro. It is refused, and nothing changes, in four cases:

  • the move is to free and the account already has a live Free application;
  • during the beta, the move is to standard or pro and the account already has a live application on that plan;
  • the target plan has a quantity that is not set yet;
  • the application's declared schedules do not fit the target plan.

Before it records the plan, set_plan applies two settings where the application has the resource:

  • warm_floor, the number of production copies kept running at all times: 0 on free, 1 on standard and pro;
  • connection_limit, the number of database connections each process may hold open at once, which is the maximum size of the client's pool.

Where the application has a development environment, on pro it also keeps one copy running; on free and standard it keeps none. No member of the result reports the development figure, and a change to it takes effect at the environment's next deploy.

If applying a setting fails, the recorded plan does not change, and a setting already applied is not undone. Call set_plan again to retry.

The database role takes the new connection limit at once, but a running copy keeps the APP_DATABASE_CONNECTION_LIMIT it started with, the setting its pool reads. So after a move, set_plan's detail names restart_application for each environment whose running copy has a database. The restart re-creates the running copy under the new limit, and a deploy or promote does the same. The connection limit says what a move to a smaller plan does until then.

3. Read the usage

read_usage takes an optional application identifier. Without it, the call returns usage for every live application of the account. A token bound to one application must name that application.

Each application in the response has five measures:

Measure What it counts
backend_actions Requests the router forwards to your backend, scheduled runs included, plus end-user sign-ins and session verifications, one each
data_transfer_bytes Bytes sent to clients, downloaded from the storage areas, and sent by the backend through the gateway or the tunnel, this month. A download that ends early because the caller closed the connection counts the bytes sent. A download that the platform itself cuts short does not count.
stored_data_bytes The live database and the stored files, as one pool
ai_allowance_units Units of the included AI allowance drawn this month
push_messages Push deliveries the push service accepted this UTC month, one per device a send accepted, against the plan's push-messages-capacity quantity

Every environment the application has counts toward its one plan. On an application with one environment, read_usage also shows what local runs drew, in a local_runs line described below. The read_usage reference describes every member of the response.

An application's issue-tracking spaces, where its backend files its users' reports, count toward no measure. Their calls and their stored records use none of the plan's quantities, and no usage state refuses them.

A measure's month_total is this month's figure. Compare it with quota, and add nothing to it. It has two parts, which stand beside it. used is the reading of the last daily check, taken at checked_at. live is this month's traffic since that check. Where live is null, month_total is used. On the two traffic measures month_total follows this rule:

  • where checked_at falls in the response's period, it is used plus live;
  • otherwise, used belongs to an earlier month, and it is live alone.

On backend_actions, one unit is each request the serving router forwards to your backend, a scheduled run among them, plus each end-user sign-in and each session verification the accounts service performs. A request the router verifies itself counts once. The router's count reaches live within about a minute, and sign-ins and verifications reach the measure at the daily check.

The router sends its counts once a minute on its own timer. So a request can show in the router's per-minute log records before live counts it, and a count whose send fails is never added. When records arrive, and in what order says when the log records arrive.

Stored data has no live term, so its live is null. For the allowance, live is also null, used is the units drawn this month, and the state is computed at each read.

The push messages read the same way: live is null, used is this month's accepted deliveries, and the state is computed at each read. When the month's accepted deliveries first pass the warning_fraction of the quantity, the send writes one usage warning event into the application's log stream for each environment.

Beside its measures, each application has an egress_limits member for its outbound traffic. It contains the plan's two outbound limits: connections_per_minute, counted on each proxy replica, and bytes_per_day. The pricing page lists each plan's two figures: 60 connections a minute and 500 MB a day on Free, 300 and 2.5 GB on Standard, and 1,200 and 25 GB on Pro. Each limit is null where the plan's figure is not set. The member also contains bytes_today, the bytes counted so far today, and refused_today, the connections and calls refused at either limit today.

These figures cover the whole application and reset at the start of each UTC day, which the member's resets_at gives. The member's state is ok under the day limit, capped at or past it, and unset where the day limit is not set. A limit that is not set refuses nothing. Egress firewall and request limits explains what each limit counts and what happens when the application reaches it.

4. Read a measure's state

Each measure has a state:

  • ok, below 80% of the quota;
  • warning, at 80% of the quota or more;
  • over, at or above the quota;
  • unset, where the plan's quantity is not set;
  • unknown, where no state is recorded yet and the month's figure is missing or at 80% of the quota or more.

The platform updates the two traffic states about once a minute, from the serving router's reports. The stored-data state changes only at the daily check, at a plan change, or when platform staff change the stored-data quota.

Before the first daily check, used and checked_at are null and the stored-data state is unknown. A traffic measure with no recorded state reads ok below 80% of its quota, and unset where the plan sets no quota. At 80% or more it reads unknown until a router report or the daily check records warning or over. The application's own state stays unknown until a state is recorded. A measure's quota shows the plan's current quantity, which can differ from the quantity the recorded state was measured against. Use checked_at to tell which reading you have.

Until that first check, the application's entry also includes note, and the response's detail opens with a matching sentence. Both say that the daily check has not run yet and runs within a day. Until it does, the three measures it reads, backend_actions, data_transfer_bytes, and stored_data_bytes, return used as null. live on the two traffic measures is then the month's whole count, with nothing to add to it. The detail also says that unknown then means not yet measured, not a fault.

5. What an over state stops

An over state stops the metered operation and nothing else. Deploys, promotes, reads, and every management action continue.

  • Traffic over. While backend_actions or data_transfer_bytes is over, the serving router refuses the application's requests on its hostnames, and its scheduled runs, with 429 usage_over_quota. It still serves the application's page files and the sign-in routes under /__account/, so the page loads and its application programming interface (API) calls receive the refusal. The refusal lasts until the start of the next UTC month. Its Retry-After header and its detail give that time, and resets_at repeats it.
  • Stored data over. While stored_data_bytes is over, the platform refuses file puts on the application's storage areas with 429 usage_over_quota. File gets, lists, and deletes continue. The refusal lasts until a daily check, a larger plan, or a raised quota finds the application within its quantity.
  • Allowance over. While ai_allowance_units is over, the application's AI calls are refused 429 allowance_exhausted, as AI Allowance describes. This measure does not change the application's overall state.
  • Push allowance drawn. Once the month's accepted push deliveries reach push-messages-capacity, a send that would pass it is refused 429 usage_over_quota whole (Send push notifications). The refusal stops the application's sends alone and does not change its overall state. It ends at the month's first instant, at a larger plan, or at a raised quota. While push_messages is over, its refuses is push_sends and its resets_at gives the month's end.

A measure's refuses gives what is refused: requests for the two traffic measures, file_puts for stored data, ai_calls for the allowance, and push_sends for push. It is null for a measure that is not over. Its resets_at is null for stored data and for any measure that is not over. While the application is over, a deploy's response includes a usage_notice that gives the refusal and when it ends.

A refusal starts within about 90 seconds of the measure passing its quota. The router reports its counts to the platform once a minute, and the platform records the state from each report. The router reuses its copy of each application's recorded state for up to 30 seconds before it asks the platform again. So a recorded state reaches the router within about 30 seconds.

6. The start of a new month

At the start of each UTC month, the router stops refusing traffic, using its own clock. Until the first traffic report or daily check of the new month, read_usage shows a recorded over or warning on the two traffic measures as ok, with null refuses and resets_at. When a report or check of the new month finds a traffic measure at warning or over again, it records that state and moves state_since.

The stored-data state does not reset with the month. It stays until the next daily check, a plan change, or a change to the stored-data quota.

7. How a plan change affects the states

set_plan recomputes the three states against the new plan's quantities before it responds, and its detail reports the result.

  • A larger plan clears an over state at once, stored data included.
  • A smaller plan is accepted even where usage exceeds its quantities. It records over at once, and the router starts refusing within about 30 seconds.
  • If the recomputation fails, the plan stays recorded and the detail says so. The next traffic report or daily check records the states.

Balance and billing-statement queries are not available.

8. See the plan in the browser

The dashboard's account page shows each application's plan, with a control to change it, and its usage against the plan. The application page shows that application's own usage. A plan change made from the page asks you to sign in again when your browser sign-in is more than 8 hours old.

Expected result

set_plan returns an application object with the recorded plan, warm_floor, and connection_limit. The limit is present whatever the manifest declares, and it governs the client pool once the manifest declares the database kind. Its detail sentence gives the floor, the limit, and the recomputed usage state.

Where an environment of the application runs a copy that has a database, the detail also gives the restart_application call for it, which brings the running copy's APP_DATABASE_CONNECTION_LIMIT to the new value.

read_usage returns the period as YYYY-MM, the warning_fraction, and an applications array. Each entry contains the application's id, label, plan, checked_at, overall state, and state_since, the time of the first check or of the latest change to the overall state. Before the application's first daily check, it also has note. Each entry also contains the five measures, each with month_total, quota, state, resets_at, refuses, used, and live, in that order. It also contains the egress_limits member that step 3 describes.

On an application with one environment, an entry also has local_runs when local runs stored or used anything in development this month. It gives environment (development), egress_request_bytes and storage_get_bytes for this month, database_size_bytes from the development database's last size sample, and a detail sentence. These are local runs' share of the measures above, not an extra charge.

The read_usage response also includes page, the address of this page, and a short detail. The detail says to compare each measure's month_total with its quota, and that an over measure refuses what its refuses names until resets_at, while deploys and management actions continue. It also says how soon each count reaches the measure.

read_plan_quotas returns quotas, one row per plan and quantity, or only the rows plan and measure select.

Refusals

A refusal changes nothing on the platform. The status is the one the Hypertext Transfer Protocol (HTTP) route returns, and the Model Context Protocol (MCP) tool returns the same name. Refusals lists every refusal the platform returns.

Refusal Status Cause Remedy
invalid_request 400 set_plan named a plan other than free, standard, or pro. Or read_plan_quotas over HTTP named such a plan, or a measure that is not a row's measure name. Name one of the three plans, or a measure name from a read_plan_quotas call that names no measure.
no_such_application 404 set_plan or read_usage named an application the account does not have, or one deleted during the call. Use the identifier list_applications returns.
free_application_limit 409 The move is to free, and the account already has its one live Free application. Move the other application off free first, or choose standard or pro.
beta_plan_limit 409 During the beta, the move is to standard or pro, and the account already has its one live application on that plan. The detail gives the plan, the limit, and that application. Move that application to another plan first, or choose another plan.
plan_quantity_unset 409 A quantity of the target plan is not set; the plan and measure members name it. Choose another plan, or wait for platform staff to set it. read_plan_quotas shows it as a null quantity.
plan_schedule_conflict 409 The application's declared schedules do not fit the target plan; the schedules member lists each one. Resubmit the manifest within the target plan's limits, or choose another plan.
entitlement_apply_failed 502 set_plan could not apply the replica floor or the connection limit, so the plan is unchanged. Call set_plan again. If it fails again, report it and quote the reference in the detail.
deletion_in_progress 409 The application, or one of its environments, is being deleted. Wait for the deletion to finish; read_pending_action returns its outcome.
token_scope_refused 403 A token bound to one application left out application or named another application. Name the token's application, or use your signed-in session or an account-wide token.
app_credential_not_admitted 403 The call ran under an application's platform credential, which only read_account accepts. Use your signed-in session or a minted token.
authentication_required 401 No credential matched an account. Sign in again through your tool.
fresh_authentication_required 403 A plan change from the dashboard came more than 8 hours after your browser sign-in. Follow the page's Sign in again link, then repeat the change.
usage_over_quota 429 The application is over its plan's quantity for a measure this month (step 5). Move to a larger plan with set_plan. Otherwise wait for the next month (traffic) or the next daily check (stored data).
log_capacity_reached 409 A batch of app log entries would take the environment past its plan's retained-log quantity. Erase the stream with purge_logs, wait for entries to expire after 30 days, or move to a larger plan.