> For the complete documentation index, see [llms.txt](https://docs.flora.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flora.ai/mcp/cost-and-limits.md). # FLORA MCP cost, balance and limits Price a FLORA MCP generation before it runs, read balance and spend with flora\_get\_usage, handle billing errors, and plan around refunds, spending limits and rate limits. Every paid run your agent starts through [FLORA MCP](https://flora.ai/mcp) is billed in US dollars to a workspace, at the published model rates. This page shows how to price a request before it runs, check the balance, react to billing errors, and stay inside the request and batch limits. {% hint style="warning" %} **Cost rule.** Price first: call `flora_create_generations` with `quote: true` and show the user the cost in US dollars. Run the same request without `quote` only after they approve. On `insufficient_credits` or any `BILLING_*` error, stop and pass the message on. Don't retry. Check balance and spend with `flora_get_usage`. A failed run isn't charged; a retry is a new run and is billed again. {% endhint %} ## Which plans include MCP **Starter and above** include the FLORA API and MCP. Generations your agent starts draw from the workspace's monthly usage budget at the same per-generation rates as the app, and failed generations don't count. See [How Pricing Works](/plans-and-billing/pricing.md) and [Model Pricing](/plans-and-billing/model-pricing.md). **Free** accounts can connect, read their workspaces, and generate on the $2.50 of usage every new workspace gets. There's no separate MCP trial. When that usage is spent, runs fail with `BILLING_NOT_ENOUGH_CREDITS`. Ongoing use needs Starter or above. ## What costs money | Tool | Cost | | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `flora_create_generations` | Each started generation, at the model's rate. Free with `quote: true`. | | `flora_run_technique` | The Technique's `run_cost` per run (read it with `flora_get_technique`). | | `flora_run_canvas_nodes` | Each generation node it starts. It runs right away, with no confirmation step. Timeline nodes use video editor render usage instead. | | `flora_train_lora` | One LoRA training run. | | `flora_run_action`, `flora_run_canvas_action` | Free, but the workspace plan must include actions. | | Every other tool | Free. Reads, uploads, canvas edits and sharing cost nothing. | Model rates are on [Model Pricing](/plans-and-billing/model-pricing.md). Plans, included usage and overage are on [How Pricing Works](/plans-and-billing/pricing.md). For a rough price before you pick a model, `flora_list_models` returns `estimated_cost_usd` and `estimated_seconds` for each model. ## Amounts are US dollars Every cost field the API returns is in US dollars: | Field | Where | Meaning | | ------------------------------ | -------------------------- | ----------------------------------------------------- | | `estimated_cost` | Quote entries | Estimated cost of one run of this exact request | | `charged_cost` | Started runs and run reads | What the run costs. `0.009` means $0.009, not 9 cents | | `run_cost` | `flora_get_technique` | Cost per Technique run | | `available_cost`, `total_cost` | `flora_get_usage` | Balance and spend | Keep sub-cent precision when you report amounts. Some field names, error codes and tool descriptions still use an older unit name (for example `insufficient_credits`). They refer to the same US dollar balance, so always show users dollars. ## Price a request with `quote: true` Send the exact `flora_create_generations` request you plan to run, with `quote: true` at the top level. FLORA prices each item for its resolved model, prompt, parameters and references. It doesn't reserve money, create a canvas node or start anything. ```json { "quote": true, "generations": [ { "project_id": "prj_abc", "type": "image", "prompt": "A ceramic pour-over dripper on a warm grey backdrop, soft window light", "model": "t2i-gemini-3.1-flash-image", "params": { "aspect_ratio": "1:1" } } ] } ``` Each item comes back in input order: ```json { "generations": [ { "type": "generation_quote", "model": { "model_id": "t2i-gemini-3.1-flash-image" }, "estimated_cost": 0.072, "currency": "USD", "is_estimate": true, "quoted_at": "2026-10-11T15:04:05.000Z", "expires_at": "2026-10-11T15:09:05.000Z", "assumptions": [ "One run with the request's resolved model, prepared prompt, parameters, and current reference outputs.", "Uses the existing generation estimator: a live gateway quote when available, otherwise catalog pricing where known.", "No credits reserved, no generation started, and no canvas node created. This does not check available balance or guarantee admission.", "Not a price lock. Final usage, discounts, routing, model prices, and reference outputs can change the final charge; requote after expiry." ], "index": 0, "ok": true } ] } ``` How to read it: * **Show `estimated_cost`**, in dollars. The real response also carries `estimated_usage_credits`, an older unit; ignore it. * **Quotes expire after five minutes** (`expires_at`). Quote again if the user takes longer to decide. * **A quote isn't a price lock** and doesn't check the balance. The run can still cost a little more or less, or be refused for balance. * **Quote entries have no `run_id`.** Nothing started, so there's nothing to poll. * **To approve, send the same request without `quote`.** For a batch, quote every item, or quote one item and multiply when every item uses the same model and `params`. A quote can fail on its own: `"Pricing is temporarily unavailable. No generation was started."` means try again shortly, and `"The requested model is unavailable for quoting."` means check the `model` with `flora_list_models`. Other tools have no quote mode. For a Technique, read `run_cost` from `flora_get_technique`. Before `flora_run_canvas_nodes`, quote the same model, prompt and `params` with `flora_create_generations`, or use the model's `estimated_cost_usd`, and get approval first. ## Price without a project A quote needs a `project_id`. To answer "what would this cost?" before there's a project, multiply the model's `estimated_cost_usd` from `flora_list_models` by the count. That's the base price of one generation at default parameters, before parameter surcharges (such as a higher resolution or a longer clip, listed on [Parameter Pricing](/plans-and-billing/parameter-pricing.md)) and plan discounts, so present it as an estimate. An `estimated_cost_usd` of `0` doesn't mean free. Once the user wants to go ahead, create the project (free) and quote the exact request. ### Example: 10 Nano Banana 2 images and my balance The user asks: "What would 10 Nano Banana 2 images cost, and how much do I have left?" **Which Nano Banana?** The names map to different models and prices: plain Nano Banana is `t2i-nano-banana` (about $0.047), Nano Banana 2 is `t2i-gemini-3.1-flash-image` ($0.072), and Nano Banana Pro is `t2i-gemini-3-pro` ($0.18). If the user just says "Nano Banana", ask which one. The names-to-IDs table in [Generate an image or video](/mcp/recipes/generate.md) lists more. 1. Find the model and its price with `flora_list_models`: ```json { "type": "image", "query": "gemini-3.1-flash-image" } ``` The text-to-image entry in the result (it also carries `estimated_credits`, an older unit; ignore it): ```json { "model_id": "t2i-gemini-3.1-flash-image", "name": "Nano Banana 2", "type": "image", "provider": "gemini", "capabilities": ["text-to-image"], "estimated_cost_usd": 0.072, "estimated_seconds": 65, "param_count": 4 } ``` 2. Find the workspace with `flora_list_workspaces`. Use `current_workspace_id` if it's returned. If there are several workspaces and none is current, name them and ask which one the user means. 3. Read the balance with `flora_get_usage`: ```json { "workspace_id": "ws_123" } ``` ```json { "workspace_id": "ws_123", "currency": "USD", "balance_scope": "caller", "available_cost": 41.27, "spend": { "status": "unavailable", "reason": "permission_missing" } } ``` 4. Answer in US dollars, with the caveats: > 10 Nano Banana 2 images would cost about **$0.72** (10 × $0.072 at default settings; higher resolutions cost more). You have **$41.27** available in this workspace right now. That's your own allowance here, not the whole workspace's balance. Want me to create a project and get an exact quote before anything runs? How to read the balance in the answer: * `balance_scope: "caller"` means `available_cost` is your own allowance, held to any limit an admin set on you. `balance_scope: "workspace"` means it's the workspace's pool, which other workspaces in the organization may share. Never add balances across workspaces. * `available_cost` doesn't reflect a workspace spend limit and doesn't guarantee the next run is admitted. * `"reason": "permission_missing"` only means you can't see the workspace's spend. It doesn't mean zero spend. If the user then approves, quote the exact request (`quote: true`) and show its total. Say that the quote is good for five minutes (`expires_at`) and isn't a price lock, then run it after a yes. ## Get approval, then run The cost rule exists because generation spends the user's money and can't be undone. A good agent: 1. Quotes the exact request and states the total in dollars ("4 images × $0.072 = about $0.29"). 2. Waits for an explicit yes. 3. Runs the same request without `quote`. 4. Reports `charged_cost` from the finished runs. A started run already shows `charged_cost` (an estimate until the run settles). Read the finished runs with `flora_list_generations` for the final figure. ## Check balance and spend with `flora_get_usage` `flora_get_usage` reads one workspace (`workspace_id`) or one organization (`organization_id`). Pass exactly one. Get both IDs from `flora_list_workspaces`. ```json { "workspace_id": "ws_123" } ``` A workspace read returns the balance and, when you're allowed to see it, the spend for a date range: ```json { "workspace_id": "ws_123", "currency": "USD", "balance_scope": "workspace", "available_cost": 41.27, "spend": { "status": "available", "scope": "workspace", "period": { "start_date": "2026-09-12", "end_date": "2026-10-11" }, "total_cost": 58.73, "classified_runs": 412, "runs_by_category": { "text": 3, "image": 380, "video": 21, "audio": 0, "technique": 8 } } } ``` What the balance covers depends on who's asking: | `balance_scope` | Who gets it | `available_cost` is | Spend | | --------------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------- | | `workspace` | People with billing permission, on a plan that includes usage reporting | What the workspace's pool can still fund (included, prepaid and enabled overage) | The whole workspace's `total_cost` and run counts | | `caller` | Everyone else, including billing admins on a plan without usage reporting | Your own allowance, held to any limit on you. `member_limit` shows that limit when one applies | `"status": "unavailable"` with a `reason` | When spend is unavailable, the `reason` says why. Relay it as is; it never means zero spend: | `reason` | Meaning | | --------------------- | --------------------------------------------------------- | | `entitlement_missing` | The plan doesn't include usage reporting | | `permission_missing` | You don't have billing permission on the workspace | | `summary_unavailable` | The totals couldn't be computed. Try a shorter date range | Rules for reading it: * **Never add balances across workspaces.** Workspaces in one organization can share a pool, so the same money shows up in each. * `available_cost` is the balance right now, whatever date range you ask for. It doesn't reflect a workspace spend limit and doesn't guarantee the next run is admitted. * Dates are inclusive UTC days (`YYYY-MM-DD`). The default is the 30 days ending today. A workspace range covers at most 31 days and can't end after today. * An **organization** read returns spend only, no balance: `total_cost`, `total_runs` and `runs_by_category` across all its workspaces. Add `group_by` (`workspace`, `model` or `day`) for one breakdown. It needs billing permission in an organization with multiple workspaces, and the range can cover up to 366 days. * An API key needs billing permission on the workspace. Other workspaces and organizations return `403`. ## When the money runs out Billing errors arrive in two places: * **When a run is refused at the start.** `flora_run_technique` and `flora_train_lora` return HTTP `402` with code `insufficient_credits`. * **On a run that fails.** A generation started with `flora_create_generations` or `flora_run_canvas_nodes` is created first, then fails with a `BILLING_*` `error_code` when you poll it. The message for an empty balance ends with "About FLORA credits: ". Stop, pass the message and that link to the user, and don't retry. Don't push an upgrade: the user or an admin decides what to do. | Code | What happened | Who can fix it | | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | `insufficient_credits` (HTTP 402) | The balance can't cover a Technique run or LoRA training | Whoever manages billing | | `BILLING_NOT_ENOUGH_CREDITS` | The balance can't cover this run | Whoever manages billing ([plans and overage](/plans-and-billing/pricing.md#extra-usage-on-demand-spending)) | | `BILLING_FAILED_TO_RESERVE_CREDITS` | FLORA couldn't hold the run's cost, treated the same as an empty balance. The message carries the same "About FLORA credits" link | Whoever manages billing. Contact support only if `flora_get_usage` shows the balance is actually fine | | `BILLING_WORKSPACE_MEMBER_USAGE_LIMIT_EXCEEDED` | You hit your member limit in this workspace | A workspace admin ([workspace member usage limits](/organizations/organizations.md#workspace-member-usage-limits)) | | `BILLING_ORGANIZATION_MEMBER_USAGE_LIMIT_EXCEEDED` | You hit your limit across the organization | An organization admin ([organization member limits](/organizations/organizations.md#organization-member-limits)) | | `BILLING_CREDITS_LIMIT_EXCEEDED`, `BILLING_WOULD_EXCEED_LIMIT` | The run would go past a limit an admin set | A workspace admin | | `GENERATION_NOT_PAID` | The run needs payment first | Whoever manages billing | In a batch, the first billing error means every later item fails the same way. Stop firing, report what finished, and relay the message once. ## Refunds and retries * **A failed run isn't charged.** As in the app, [failed generations don't count](/plans-and-billing/model-pricing.md). FLORA holds the run's cost when it starts and releases it if the run fails, and the same goes for failed Technique runs. * **A retry is a new run and is billed again.** Retry only failures that a retry can fix. See the error classes in [Runs](/mcp/runs.md#error-codes). * **Never re-fire a whole batch after a partial failure.** The items that succeeded already cost money. * **After a timeout, read history before retrying.** `flora_create_generations` has no idempotency key, and a create that timed out may still have started. See [Runs](/mcp/runs.md#after-a-timeout-check-before-you-retry). * **Cancelling doesn't always stop the charge.** There's no cancel tool. Cancelling a node in the canvas stops a run that hasn't reached the model provider yet, but a run the provider has already accepted keeps going and is still billed. ## Spending limits and member limits Admins can cap spend so an agent can't run past a budget. Every limit applies to MCP and API runs exactly as it does in the canvas: * **Workspace member usage limit:** one person, in one workspace. * **Organization member limit:** one person, across every workspace in the organization. * **Workspace spend limit:** everyone in one workspace together. * **Max overage:** the most extra usage a workspace allows per billing period, once included usage runs out. Set them in [Workspaces](/faqs-how-to.../workspaces.md#checking-your-usage), [Organizations](/organizations/organizations.md#usage-limits-at-a-glance) and [How Pricing Works](/plans-and-billing/pricing.md#your-max-overage-cap). `flora_get_usage` shows the limit that binds you as `member_limit`. ## Rate and size limits | Limit | Value | When you go over | | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | API requests | A per-minute limit, counted against your credential's [default workspace](#default-workspace) (not the `workspace_id` you pass) and shared with every agent, API key and script that counts against the same workspace | HTTP `429` `rate_limited` ("Rate limit exceeded."). If the error has `retry_after_seconds`, wait that long; if not, back off about 60 seconds. Then retry reads. Don't blindly retry a create: check history first | | Polling one batch | Once every `max(15 s, 2 s × run_ids)`, so 40 seconds for 20 runs | A cooldown error with `retry_after_seconds` and no run data | | Generations per `flora_create_generations` call | 1 to 20 | `generations must contain 1–20 requests` | | `run_ids` per `flora_list_generations` call | 1 to 20 | `run_ids must contain 1–20 non-empty run id strings` | | Files per `flora_create_asset` or `flora_complete_asset` call | 25 | Split into several calls | | `reference_node_ids` per generation | 20, including `@[nodeId]` mentions in the prompt | Rejected with the count | | Nodes per `flora_run_canvas_nodes` call | 50 | Rejected by the schema | | Per `flora_add_to_canvas` call | 200 nodes and 500 edges | Rejected by the schema | | Nodes per `flora_arrange_canvas` call | 500 | Rejected by the schema | | Quote validity | 5 minutes | Quote again | ### Default workspace Every credential has a default workspace. For an API key, it's the first workspace the key was granted. For an OAuth sign-in (Claude, ChatGPT and most clients), it's the earliest-joined of your workspaces whose plan includes API access, or your Free workspace if none does. It matters in two places: * **Rate limits** are counted against it, whatever `workspace_id` a call names. * **`flora_run_technique`** takes no `workspace_id`, so a Technique run bills the default workspace. See [Run your team's Technique](/mcp/recipes/run-a-technique.md#where-it-bills-and-where-the-outputs-go). Every other tool acts on the `workspace_id` you pass, or on the workspace that owns the `project_id`. FLORA doesn't publish a fixed requests-per-minute number. The limit counts API requests, not tool calls: each `run_id` in a poll is one request, so one read of a 20-run batch is 20 requests. One `sources` call to `flora_create_asset` reserves up to 25 uploads in a single request. **Concurrent runs.** Paid accounts have no fixed cap on how many generations run at once. New accounts that haven't paid run one generation at a time for their first 7 days; extra runs wait as `pending`, and a run that can't start within an hour fails with `GENERATION_QUEUE_NOT_MOVING`. A busy model can also refuse work with `GENERATION_QUEUE_TOO_LARGE`. Wait and retry later, or pick another model. ## Related * [Runs: polling, timeouts and failures](/mcp/runs.md) * [Troubleshooting](/mcp/troubleshooting.md#billing) * [Security and data](/mcp/security.md) * [How Pricing Works](/plans-and-billing/pricing.md) and [Model Pricing](/plans-and-billing/model-pricing.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.flora.ai/mcp/cost-and-limits.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.