---
title: Size and usage
description: Change an application's size and sleep setting, read usage and limits, and understand what happens when the account uses its balance.
slug: /guides/plan-and-usage
order: 30
visibility: public
redirects_from: [/guides/size-and-usage]
---

# Size and usage

Prompt:

> Give this app more memory. How much have we used this month?

Also works:

- "What limits apply to this app?"
- "Why is my app answering 429?"
- "Let production sleep when nobody is using it."

An application's [size](/cloud/concepts/glossary/#size) sets its production compute capacity. Your AI tool reads limits with `read_plan_quotas` ([step 1](#1-choose-a-size)) and changes the size or sleep setting with `set_app_size` ([step 2](#2-change-the-size)).

For this month's cost, balance and pause, it reads `read_balance`. For an application's quantities and limits, it reads `tzcloud_read_usage` ([step 3](#3-read-the-usage)).

At your request, your AI tool calls `buy_credits` with an `amount` its schema admits. If prepaid credit is not sold on the site, the call returns `credit_sales_off`, opens no checkout and charges nothing. An admitted purchase returns `checkout_url`; you open it and pay on the payment provider's page. The call itself takes no payment and grants no prepaid credit.

Call `read_purchases` for your account's purchases, newest first, whether or not prepaid credit is sold on the site. This read changes nothing. Pass `purchase` to read one; an identifier outside your account returns an empty list.

Sleeping when idle stops the running copy, not the database or storage service. Database records, files in storage areas, secrets and settings stay. Data held only in memory or written to the copy's own disk is lost ([What survives an idle stop](/cloud/concepts/how-the-plans-differ-technically/#start-after-idle-and-response-time)).

## What your AI tool does

- Reads the `cost-review` [skill](/cloud/concepts/glossary/#skill) (`read_context`, id `skill:cost-review`) and follows it.
- Takes the application's identifier and current `size` from `list_applications`.
- Calls `read_plan_quotas` for limits, `read_balance` for cost and balance, and `tzcloud_read_usage` for quantities. It reads rates through `read_rate_card` or the [pricing page](https://turnzero.ai/pricing).
- Waits with `read_status` for any returned `applying.version`. Restarts each [running copy](/cloud/concepts/glossary/#running-copy) with a database that was not re-created, so its connection setting is refreshed.
- Changes no size or sleep setting unless you ask; for a usage or limits question, it reads and reports.
- Asks which size or sleep setting you want if your request does not say, before calling `set_app_size`.

## What you need

- For a size change, choose Shared 0.5 GB or Shared 1 GB. For a sleep-setting change, say whether production should sleep when idle.

## Before your AI starts

**For the AI tool:** Check these prerequisites before changing the application's size or reading its usage.

- A connected, signed-in AI tool ([Connect your AI assistant](/cloud/getting-started/connect-your-tool/)).
- The application's identifier, which `list_applications` returns.

## Steps

For the prompt above, read usage in step 3 and ask which size the person wants before changing it in step 2. If the size call returns `applying`, read that version's outcome and the setting in `read_status` before reporting success.

<div id="1-choose-a-plan"></div>

### 1. Choose a size

Choose `shared-0.5gb` or `shared-1gb` as `size` when calling `create_application`. Use `set_app_size` to change it later. With nobody to ask, start on Shared 0.5 GB and say it draws the account's Free Allowance.

Every account gets [Free Allowance](/cloud/concepts/glossary/#free-allowance), drawn first across its applications and paid options; there is no plan to choose. For a server, Shared 0.5 GB with its default sleep setting can reduce costs.

Free Allowance is enough for most static websites and for a small app with a shared database on Shared 0.5 GB that sleeps when idle. The **Static website** and **Small app** examples in the [calculator](https://turnzero.ai/pricing#estimate) fit without the introduction bonus. A server that stays awake all month can exceed the Free Allowance. Other apps and paid options share the same Free Allowance.

A static website has no server, per-request or file storage charge; its data transfer still counts against the account's Free Allowance. Open the [pricing calculator](https://turnzero.ai/pricing?example=static#estimate) for **Static website**. It compares a fixed example's full month with Free Allowance and, while its box is ticked, the introduction bonus. A custom domain, where available, is a separate monthly item.

The account's `account-application-limit` applies until it holds prepaid credit. Unbilled accounts are exempt.

At creation, Shared 0.5 GB uses shared compute and sleeps when idle by default; Shared 1 GB uses its own container and keeps running. For an existing application, read `production_sleep` in `read_status`: size alone does not determine it. You can change production's setting. Development always sleeps when idle and is charged at the Shared 0.5 GB rate.

Usage draws the account's balance at the rates on the [pricing page](https://turnzero.ai/pricing) or in `read_rate_card`. A development environment's use is charged too ([Test in development, then promote](/cloud/guides/turn-on-development-and-promote/)).

Every application can [attach a custom domain](/cloud/guides/attach-your-own-domain/) and [send email](/cloud/guides/send-email-from-your-application/). A custom domain is a monthly item. Each email recipient is charged, including an emailed sign-in code. Read `email-recipients-per-hour` and `email-recipients-per-day` for the send limits.

A shared database is a monthly item for the application, covering production and development together. It remains charged while servers sleep, until the application is deleted. Monthly items are charged at the start of each calendar month, or for the days left when added. Removing one returns nothing. An existing item is first charged on the month's first day after the switch.

Read limits with `read_plan_quotas`; [Size limits](#size-limits) explains the rows. An application has no monthly AI allowance. The platform's AI calls draw the account's balance at the provider's published price plus the pricing page's markup. Calls on your own stored key have no markup and deduct nothing from that balance.

<div id="2-change-the-plan"></div>

### 2. Change the size

Pass `application` to `set_app_size` with at least one of `size` and `production_sleep`. The size is `shared-0.5gb` or `shared-1gb`; `production_sleep` is a boolean. Development always sleeps when idle, so it has no sleep setting.

```json
{ "application": "<application id>", "size": "shared-1gb" }
```

Where `changed` names a member, the call recorded that value and `application` holds it. A repeat naming values already in effect writes nothing.

Where `applying` is present, `changed` is empty and `application` still holds the old size and sleep setting. Read `applying.environment` and `applying.version`, then call `read_status` with the application and `wait_seconds` until that version ends. The new values are recorded only when the new compute takes traffic. A failed or ended redeploy records neither.

A deploy, promote or redeploy in flight on production refuses any size or sleep-setting call with `deploy_in_flight`, even for the values already standing. The call records nothing. Wait for that version to end, then repeat the call.

<div id="what-a-move-does-to-the-running-application"></div>

#### How production takes the change

Shared 0.5 GB runs on shared compute. Shared 1 GB runs in its own container ([How the sizes differ technically](/cloud/concepts/how-the-plans-differ-technically/)). Read the call's answer to learn how production takes a size or sleep-setting change.

Where `applying` is present, production is being re-created once, with one cold start. The new copy takes traffic after its health check. The old copy serves until then, so no request waits for that cold start.

If a change would re-create halted production, the call returns `target_environment_halted`. Resume production with `halt_environment` and `resume: true`, then repeat the call. Read the [refusal reference](/cloud/reference/refusals/) if a capacity or provider refusal prevents a change.

During a re-creation, `applying.size` names a requested size where one moves; `applying.production_sleep` names a requested sleep setting where one moves. Read the members returned by the call.

`application` keeps reporting the previous values until the new compute takes traffic. If re-creation fails, production keeps serving its earlier compute and the previous values remain recorded. Read the failure through `read_status`; the same call is the retry.

Neither size adds copies under load. Compare CPU and memory in [How the sizes differ technically](/cloud/concepts/how-the-plans-differ-technically/), and quantity rows with `read_plan_quotas`.

Read `database-connection-limit` for the limit per process. A running database environment not re-created by the change reads its connection setting only at its next restart, deploy or promote.

Restart such an environment after the change; production re-created by the change needs no further restart. The size act's answer does not list environments needing a restart.

For production written in place, `restart_application` takes the form below. Name `development` instead for a running development copy with a database.

```json
{ "application": "<application id>", "environment": "production" }
```

[The connection limit](/cloud/guides/add-a-database/#the-connection-limit) explains the pool setting and when a running process reads it.

A size change made in place recomputes the usage states before the call answers. Where production is re-created, the states follow at the next router report or daily check. Read usage again to see the recorded state; the size call carries no recomputation `detail`.

Email and custom domains remain available at either size.

On the dashboard, **Balance & usage** has **Monthly summary**, **Account charges** and **By application**. It reads `read_account` for account details and `read_balance` for the balance, warnings and pause with its end. Each application's card shows a server size where recorded, its environment sleep settings, and any log entries refused at the size limit during the last day.

**Applications no longer in this account** groups moved or deleted applications whose usage remains in the month. Each card and that group end with **Usage subtotal**.

Use **Change size** on the application's own page to choose a size or change production's sleep setting. The control reads the sizes from `read_plan_quotas` ([Use the signed-in site](/cloud/guides/your-account/#3-use-the-signed-in-site)).

### 3. Read the usage

For cost, balance or a pause, call `read_balance`. Its `balance` gives what was drawn and what is left; `state.paused` and `state.paused_until` say whether the account is paused and when it ends.

Its `lines` identify charges by rate key, application and environment. Its `applications` show each application's size, sleep settings and refused log entries.

For quantities and limits, call `tzcloud_read_usage`.

`tzcloud_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.

```json
{ "application": "<application id>" }
```

Each application in the response has six measures:

| Measure | What it counts |
| --- | --- |
| `backend_actions` | Requests the router forwards to your backend, [scheduled runs](/cloud/concepts/glossary/#scheduled-run-and-due-instant) included, plus the messages clients send on WebSocket connections, 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, a deploy's zips among them, as one pool. The daily check reads it, so what is stored after the check counts at the next one. |
| `ai_allowance_usd_micros` | The application's [AI spend](/cloud/concepts/glossary/#ai-calls) this month, in micro-dollars. The key keeps its name; the application has no included AI allowance. |
| `push_messages` | Push deliveries the push service accepted this UTC month, one per device a send accepted, against the size's `push-messages-capacity` quantity |
| `email_recipients` | Recipients the email service's accepted sends addressed this UTC month, `to` and `cc` together. The month's `quota` is null. Its `hour` and `day` members count against `email-recipients-per-hour` and `email-recipients-per-day`, each with its own `resets_at`. |

Every environment counts toward the application's one size. On an application with one environment, `tzcloud_read_usage` also shows what [local runs](/cloud/concepts/glossary/#local-run) drew, in a `local_runs` line that Expected result describes. The [`tzcloud_read_usage` reference](/cloud/reference/actions/read-usage/) describes every member of the response.

An application's own [issue-tracking space](/cloud/concepts/glossary/#issue-tracking-space) counts toward neither the account's space limit nor its open-issue limit. tzTrack AI reviews remains a paid option for each space, an application's own space included ([Space limits and tzTrack AI reviews](https://turnzero.ai/tztrack/concepts/free-and-paid-tiers/)).

#### Compare usage with the quota

Compare a measure's `month_total` with its `quota` where a quantity is set. A null `quota` means the size holds no quantity for that measure. `includes_before` gives the source timestamps for the total, and `freshness` explains what recent activity may still be missing.

The two traffic totals include the month's router counts. They also include the daily check's terms when that check falls in the response's `period`. Stored data is the size from its last check, even if that check was in an earlier month.

For a quantity question, compare stored data with `stored-data-capacity` and accepted push deliveries with `push-messages-capacity`. Stored data is a ceiling against abuse, not an allowance.

The traffic measures have null `quota` and state `ok`. AI spend and the email month have null `quota` and state `unset`. They never read `over`. Read cost and balance through `read_balance`.

Report shorter periods separately. These are `egress_limits.bytes_today` against `bytes_per_day`, `deploys-per-day` over the last 24 hours, `signin-code-sends-per-hour`, and email's `hour` and `day` windows. They do not describe use for the UTC month.

#### Check which activity is counted

Each measure's `includes_before` is null when its `month_total` is null. Otherwise, it contains only the sources included in that figure; no source key has a null value:

| Measure | Members of `includes_before` |
| --- | --- |
| `backend_actions`, `data_transfer_bytes` | `router`, two minutes before the read or the application's `created_at`, whichever is later. Also `daily_check`, the application's `checked_at`, only when that check falls in the response's `period` |
| `stored_data_bytes` | `daily_check` whenever a check has run, even in an earlier month |
| `ai_allowance_usd_micros`, `push_messages`, `email_recipients` | `read`, the time of this read, when a count was read |

Before the first check, or after a check in an earlier month, the two traffic measures have `router` alone. Stored data before its first check has `includes_before: null`. A read-at-call measure also has `includes_before: null` if no count was read.

`created_at` is the creation time returned by `create_application` and `list_applications`; deploying or changing size does not move it.

The `router` timestamp means requests and WebSocket messages that ended before it are counted, unless a report was lost. Later router traffic may already be counted in `month_total`; the timestamp is not its upper limit.

In `read_status`, `server_errors.counted_through` stays two minutes before the read ([Read logs and counters](/cloud/guides/read-logs-and-counters/#the-failing-paths-in-the-status)).

Sign-ins and session verifications enter `backend_actions` at the daily check; outbound request bytes and storage downloads enter `data_transfer_bytes` at that check. Activity in these daily-check terms after `checked_at` waits for the next check.

Stored data is the amount stored at the latest daily check: the sum of each environment's newest database size sample and file bytes in the application's bound storage areas. It does not reset with the month. Its `daily_check` timestamp marks that check. The database size samples it used may be older.

The response's `freshness` sentence explains what may be missing. Router counts normally take about two minutes to arrive. The next daily check adds sign-ins, verifications, outbound request bytes, storage downloads and stored data.

#### How the measures are counted

On `backend_actions`, units count one per request the [serving router](/cloud/concepts/glossary/#serving-router) forwards to your backend, a scheduled run among them, and one per data message a client sends on a WebSocket. Each end-user sign-in and each session verification the accounts service performs also counts one. A request the router verifies itself counts once. The router's count reaches `month_total` and `by_environment` up to a minute after a request is answered. A WebSocket message takes up to two minutes, because the router meters it once a minute first. Sign-ins and verifications reach the measure at the daily check.

On a WebSocket connection, the upgrade counts one unit, and each data message the client sends counts one more; [Limits and metering](/cloud/guides/use-websockets/#limits-and-metering) says what else a connection counts and gives its own limits.

The router sends its counts once a minute, so a read soon after a request may not count it yet, and the request can show in the router's per-minute log records first. A count the router cannot send, on a failed send or a router stopped abruptly, is never added. [When records arrive, and in what order](/cloud/concepts/how-log-records-arrive/#when-records-arrive-and-in-what-order) says when the log records arrive.

On the two traffic measures, `by_environment` splits the router's count between `development` and `production`, and is null until the router names environments.

Stored data's `month_total` is the amount stored at the latest daily check, as the `daily_check` timestamp describes above. Before the first check it is null: the size has not yet been sampled. A deploy or upload since `checked_at` shows at the next check.

For AI spend, push and email, `month_total` is this month's micro-dollars, accepted deliveries or recipients, read at the call. The push state is computed at each read.

When accepted push deliveries first pass the `warning_fraction` of `push-messages-capacity`, the send writes a `usage warning` event into each environment's log stream. Email has no month quantity for a size, so it fires no month warning.

#### Other usage limits

Beside its measures, each application has `egress-connections-per-minute` and `egress-bytes-per-day` limits. [Outbound limits](/cloud/concepts/egress-firewall-and-request-limits/#outbound-limits) explains what counts and what happens at a limit.

Other limits include `deploys-per-day` and retained-log quantities for each environment. Read the application's current limits with `read_plan_quotas`.

`egress_limits.state` reads `ok`, `capped` or `unset`. Its `resets_at` is the next UTC day's start.

The retained-log size limit applies separately to your entries and the runtime harness's entries. At the limit, new entries are refused and the platform writes its own warning into the stream ([Read logs and counters](/cloud/guides/read-logs-and-counters/#9-stay-under-the-retained-bytes-limit)).

Call `set_log_retention` with `days: 30` to turn extended retention on, or `days: 7` to turn it off. Turning the extended option on charges at once for the days left in the calendar month; removing it returns nothing. The call can be refused `balance_short` (402) or `rates_unread` (503).

Read its rate on the [pricing page](https://turnzero.ai/pricing). Turning it off makes the next retention run delete entries older than the standard period; turning it on again does not restore them.

### 4. Read a measure's state

The response's `warning_fraction` is the warning point for a measure with a quantity, read from `low-capacity-warning`. It is separate from the account's balance warnings. Stored data and push can have these states:

- `ok`, below the warning point;
- `warning`, at the warning point or above, but below the quota;
- `over`, at or above the quota;
- `unknown`, where no state is recorded and the figure is missing or has reached the warning point.

The traffic measures have state `ok` and no quantity. AI spend and the email month have state `unset` and no quantity. A size includes email, so its email measure never reads `not_on_plan`.

Stored data changes at a check, at a size change made in place, or when platform staff change `stored-data-capacity`. Push is read when usage is read.

Until a check succeeds, `checked_at` and stored data's `month_total` are null, and the stored-data state is `unknown`. After each successful deploy, the platform attempts a usage check if no successful check is recorded. The platform waits up to two minutes for that attempt, including time waiting behind another check. A check already started can finish later. The daily check also runs once a day.

Read `tzcloud_read_usage` again about two minutes after `tzcloud_read_status` answers `settled: true` with `state` set to `deployed` ([Read the status](/cloud/getting-started/deploy-an-application/#5-read-the-status)). If `checked_at` is still null, no successful check is recorded yet; report stored data as unknown. The next daily check runs within a day. Reading usage starts no check.

For stored data or push with no recorded state, a missing figure or one at the warning point or above reads `unknown`. A figure below the warning point reads `ok`.

Until the first check succeeds, the application's entry includes `note`: the daily check has not run yet, or it failed at the time given. A first-deploy attempt does not change this note while it waits or runs, or if it fails or never starts. The note cannot distinguish those outcomes.

The response's `detail` also explains the missing check. The two traffic measures still answer `month_total`, with `includes_before.router` and no `daily_check`. The application's own `state` reads `unknown` until a state is recorded, which is not a fault.

A measure's `quota` shows the size's current quantity, or null where it holds none. The comparison uses the whole `month_total`; the quantity is not prorated. A change to a quota recomputes the affected measure.

A size change made in place recomputes states before it answers. Where production is re-created, the states follow at the next router report or daily check. Read usage again for the recorded state. `set_app_size` carries no `detail` about recomputation.

No response member dates an individual measure's state. `checked_at` dates the daily check, and `includes_before` describes which activity the total includes, as [step 3](#check-which-activity-is-counted) explains. `state_since` dates the first check or the latest change to the application's overall state. None identifies which quota an individual state was measured against.

### 5. What an `over` state stops

An `over` measure stops its own operations. Reads and size changes continue. Stored data and push are the only measures that can read `over` for a customer application.

- **Stored data over.** The platform refuses file puts on the application's storage areas, a new deploy's upload, and `tzcloud_deploy_files` calls carrying file contents or a stored entry with 429 `usage_over_quota`. It also refuses `generate_image` calls naming that application; pictures saved in the account are unaffected. File gets, lists and deletes continue. Store less; the next daily check reads the reduced size.
- **Push quantity reached.** A send that would pass `push-messages-capacity` is refused 429 `usage_over_quota` whole ([Send push notifications](/cloud/guides/send-push-notifications/)). This stops the application's sends alone and does not change its overall `state`. Wait until the next UTC month; `resets_at` names its first instant.
- **Email hour or day limit reached.** A send that would pass `email-recipients-per-hour` or `email-recipients-per-day` is refused 429 `email_limit_reached` whole. The refusal names the period and its end in `resets_at`. Wait for that reset. For more sends, use your own provider on a declared egress upstream.

A measure's `refuses` is `file_puts` for stored data over and `push_sends` for push over. It is null for a measure that is not `over`. Stored data has null `resets_at`: it has no monthly reset. A deploy's answer includes a `usage_notice` while stored data is over.

Stored data changes at a daily check, a size change made in place, or a staff change to `stored-data-capacity`. A monthly count starts again at the first instant of the next UTC month. Email's hour and day counts reset at their next UTC boundary.

#### When the account pauses

A billed account pauses when its Free Allowance for the month is set and used up and it holds no live credit. Read `read_balance` for `balance.left`, `state.paused` and `state.paused_until`. This pause is separate from an application's quantity limit.

- Application requests and scheduled runs are refused `account_paused`, including requests for the web client's shell and sign-in routes.
- Storage reads, lists, puts, deletes and grant mints are refused 429 `account_paused`. Egress is refused before reaching the upstream.
- A new WebSocket upgrade is refused. An open socket closes with code 1008 and reason `account paused`.
- Platform AI calls are refused 429 `account_paused`, with `Retry-After` ([Use the AI package](/cloud/backend-packages/ai-allowance/)).
- Deploy, promote, roll back, restart and resume are refused 409 `account_paused` before a row is written.

The deploy's check, management reads, settings, secrets, a halt, export, deletion and the owner's sign-in remain available. Data is kept. Unlimited applications, which belong to Turn Zero, and operated applications are unaffected.

The pause ends at the first instant of the next UTC month, or earlier when a grant becomes live. A background pass puts paused compute to sleep and restores it when the pause ends. It leaves each environment's own sleep setting as it was.

#### Read the account's warnings

The balance read's `state.reached` gives the latest threshold reached this UTC month. With no live credit, it measures the month's Free Allowance. With live credit, it measures Free Allowance and credit together. These account warnings are separate from `tzcloud_read_usage`'s per-measure `warning_fraction`.

For the two amounts a notice shows, add the exact micro-dollar integers, not the rounded dollars strings:

| Credit at the read | Used | Base |
| --- | --- | --- |
| No live credit | `drawn_micros` | `allowance_micros` |
| `credit_left_micros` above zero | `drawn_micros` + `credit_drawn_micros` | `allowance_micros` + `credit_drawn_micros` + `credit_left_micros` |

No response member gives either sum. Under `plans`, add `shadow_micros` to used. The threshold record and balance members are separate store reads; a debit between them can leave a temporary difference until the next read.

`state.recorded` lists the warnings pass's recordings. A purchase starts the thresholds again: the next pass removes recordings made before its grant's instant, and a threshold reached again can be recorded again. An operator's grant removes none. For about a minute after a purchase, until that pass, the read can still show earlier recordings beside the new thresholds.

`state.pause_recorded_at` dates the recording of threshold 100, not a pause that stands now. It can remain after an operator's grant ends a pause. `state.paused` gives the current pause; `state.paused_until` is null unless the account is paused or would pause on the shadow basis.

If a live grant remains, `balance.credit_next_expiry_at` gives its earliest expiry instant. It is absent, never null, otherwise. Only the remainders of grants expiring then expire at that instant; later grants can remain. The read gives no amount for that expiry.

The account's warnings come by email.

<div id="what-a-plan-includes"></div>

### Size limits

Call `read_plan_quotas` for the sizes' quantities. Read rates through `read_rate_card` or the [pricing page](https://turnzero.ai/pricing); the quota response has no `prices` or `subscriptions` list.

Filter by `plan`, `measure`, or both. The argument keeps its name `plan`, but takes a size. Use `shared-0.5gb` or `shared-1gb` for the size, and a quantity name such as `schedule-count-limit` for the measure. With neither filter, the response gives both sizes' rows.

Each row gives its quantity and unit. An unset quantity reads null. With `stamps: true`, a row also carries its `set_at` and `set_by`. Any signed-in credential can read the rows, a token bound to one application included.

The response's `application_limit_exemption` names an exemption where one applies. Unbilled accounts are exempt from `account-application-limit`; that limit is not a quota row.

Every application can have a development environment; `create_environment` turns it on. Development always sleeps after the `free-idle-stop` period without a request. Production does so only when its sleep setting is on. [Start after idle and response time](/cloud/concepts/how-the-plans-differ-technically/#start-after-idle-and-response-time) explains the next request's wait.

### Current application limits

| Limit | Entry or read |
| --- | --- |
| Live applications | `account-application-limit`; this is not a quota row |
| Stored data | `stored-data-capacity`, shared by database records and files across environments, including deploy zips |
| Idle stop | `free-idle-stop`, where sleeping is on |
| Production CPU and memory | `production-replica-size`; see [How the sizes differ technically](/cloud/concepts/how-the-plans-differ-technically/) |
| Push messages | `push-messages-capacity`, accepted deliveries this UTC month |
| Database connections | `database-connection-limit`, per process |
| Schedules | `schedule-count-limit` |
| Shortest schedule interval | `schedule-minimum-interval` |
| Deploys | `deploys-per-day` |
| Log retention | `log-retention-days`, with standard or extended retention |
| Retained log size | `log-retained-capacity`, replaced by the extended option's limit where that option is on; separate limits for your entries and the runtime harness's entries |
| Open WebSocket connections | `websocket-connections-per-replica`, per environment on each serving router replica |
| Outbound connections | `egress-connections-per-minute`, per application on each tunnel proxy replica |
| Outbound data | `egress-bytes-per-day`, per application |
| Emailed sign-in codes | `signin-code-sends-per-hour` |
| Email recipients | `email-recipients-per-hour` and `email-recipients-per-day` |
| Custom domains | See [Attach your own domain](/cloud/guides/attach-your-own-domain/) |

Read current quantities with `read_plan_quotas`, and rates through `read_rate_card` or the [pricing page](https://turnzero.ai/pricing). The `limits` list in `tzcloud_read_usage` gives each other size quantity's `limit`, `count` and `resets_at`; retired quantities have no row.

## Expected result

`read_balance` answers the UTC month's cost and balance. For what is left, read `balance.left`; for a pause, read `state.paused` and `state.paused_until`. `lines` identify charged items by rate key, application and environment.

`set_app_size` answers with `application.id`, the size and sleep setting still in effect, `changed`, and `compute`. It carries no `warm_floor`, `connection_limit`, `detail` or `next`. Where `applying` is present, read its version to the end through `read_status`, then read the size and setting standing there.

`compute` names each environment whose sleep setting this call brought to its compute. Its outcomes are `unchanged`, `no_compute`, `floor_written` and `redeploy_started`. It is empty when a size moves.

The answer lists no environments needing a connection-setting refresh; restart running database environments not re-created by the change, as [step 2](#2-change-the-size) says.

`tzcloud_read_usage` returns the `period` as `YYYY-MM`, a `freshness` sentence, the `warning_fraction`, and an `applications` array. Each measure's `includes_before` gives its source timestamps, as [step 3](#3-read-the-usage) explains.

Each entry contains the application's `id`, `label`, `size`, `checked_at`, overall `state`, and `state_since`, the time of the first check or latest change to the overall state.

It contains the six measures, each with `month_total`, `quota`, `includes_before`, `state`, `resets_at` and `refuses`. The traffic measures also have `by_environment`; email has its `hour` and `day` windows. `egress_limits` and `limits` give the other limits ([`tzcloud_read_usage` reference](/cloud/reference/actions/read-usage/)).

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 local runs' share of the measures above, not an extra charge.

The `tzcloud_read_usage` response also includes `page`, the address of this page, and a short `detail`. Compare `month_total` with a non-null `quota`; `refuses` names the operation an `over` measure stops. `resets_at` gives its end where one is set.

Reads and size changes continue while a measure is over. The separate `freshness` member explains how soon activity reaches the figures. Stored data has no monthly reset; [step 5](#5-what-an-over-state-stops) explains when each restriction ends.

`tzcloud_read_plan_quotas` returns the selected sizes' rows in `quotas`, or all size rows where no `plan` is passed. That argument takes a size name. Each row gives the measure, quantity and unit; requested stamps add its writer and time.

The response has no `prices` or `subscriptions`. [Size limits](#size-limits) explains the separate account limit and the exemption member.

## Refusals

See the [refusals reference](/cloud/reference/refusals/) for other platform errors.

If `set_app_size` returns `entitlement_apply_failed`, it recorded neither a size nor a sleep setting. The same call is the retry. Report a repeated failure with its reference and detail.

| Refusal | Status | Cause | Remedy |
| --- | --- | --- | --- |
| `account_application_limit` | 409 | `create_application` found the account's counted application limit reached; nothing was created. | Read `list_applications` and report the account's limit. |
| `account_paused` | 409 | An operation would start or restart a version while the account's balance is used up. | Try again when the pause ends. You can still run `check_deploy`. |
| `balance_short` | 402 | The balance left is not more than the log option's charge for the days left. | The option stays off; report the refused charge. |
| `rates_unread` | 503 | A new option charge needs rate rows or a switch instant that could not be read. Nothing was charged. | Try again shortly. |
| `invalid_request` | 400 | A size or sleep-setting value is invalid, neither was passed, or `read_plan_quotas` named an unknown size or measure. | Pass `shared-0.5gb` or `shared-1gb`, a boolean sleep setting, or a measure from an unfiltered quota read. |
| `no_such_application` | 404 | A call named no application of the acting account, or one deleted during the call. | Use the identifier `list_applications` returns. |
| `application_other_account` | 403 | `application` names an application that another account holds, not the account the call is signed in as. The `detail` names the account the call acted as and nothing of the other one. | Compare `turnzero whoami` with `read_account` over your AI tool's connection. Make the call from the one signed in to the account that holds the application. |
| `plan_quantity_unset` | 409 | A required quantity for the target size is unset. | Read its row with `read_plan_quotas` and wait for platform staff to set it. |
| `plan_schedule_conflict` | 409 | The declared schedules do not fit the target size's limits. | Resubmit the manifest within the limits, then repeat the size call. |
| `deploy_in_flight` | 409 | Production has a deploy, promote or redeploy in flight, whatever size or setting the call names. Nothing was recorded. | Wait with `read_status` and `wait_seconds` for that version to end, then repeat `set_app_size`. |
| `target_environment_halted` | 409 | The change would re-create halted production. | Call `halt_environment` with `environment: "production"` and `resume: true`, then repeat `set_app_size`. |
| `group_full` | 409 | The shared-compute group needed by the target size is full. | Repeat `set_app_size` later; platform staff must add capacity. |
| `cell_unavailable` | 503 | Placement found no room for production's own container. | Repeat `set_app_size` later. If it persists, report the detail. |
| `entitlement_apply_failed` | 502 | A compute or connection-limit write failed; the size and sleep setting were not recorded. | Repeat the same `set_app_size` call. Report a repeated failure with its reference and detail. |
| `deletion_in_progress` | 409 | The application, or one of its environments, is being deleted. | Wait for the deletion to finish; `read_approval_status` 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. |
| `fresh_authentication_required` | 403 | A size change from the dashboard came after the browser sign-in's freshness window. | Follow **Sign in again to change size**, then repeat the change. |
| `usage_over_quota` | 429 | Stored data or accepted push deliveries reached the application's limit. | Store less, then let the daily check read it; for push, wait for the next UTC month. [The refusal reference](/cloud/reference/refusals/) gives the operation's remedy. |

## Related

- [Your account](/cloud/guides/your-account/) shows the account itself, its [standing](/cloud/concepts/glossary/#standing), and the signed-in site.
- [Deploy from your computer](/cloud/getting-started/deploy-an-application/) covers the size at `create_application`.
- [Add a database](/cloud/guides/add-a-database/#the-connection-limit) covers the connection limit each process receives.
- [Stay inside the Free Allowance](/cloud/guides/stay-inside-the-monthly-free-usage/) estimates whether a database app fits the account's remaining amount.
- [Read logs and counters](/cloud/guides/read-logs-and-counters/) covers the retained-log quantity and `purge_logs`.
- [AI Allowance](/cloud/backend-packages/ai-allowance/) describes the published package's calls.
- [Egress firewall and request limits](/cloud/concepts/egress-firewall-and-request-limits/#outbound-limits) covers the outbound limits.
- [Send email from your application](/cloud/guides/send-email-from-your-application/) covers email sends and the counts that bound them.
- The [action reference](/cloud/reference/action-catalog/) gives each action's arguments, result and refusals, including `set_app_size`, `tzcloud_read_usage` and `read_plan_quotas`.
