Billing & wallet

Satia operates under a Product-Led Growth (PLG) model with a prepaid USD wallet: connecting communication channels and creating or running Python automations is 100% free and unlimited. A workspace only consumes wallet balance for its Data Plan (System of Record), real-time AI Token / Browser usage, and optional audit log retention add-ons.

[!IMPORTANT] Financial Golden Rule:
NEVER guess, extrapolate, or invent wallet balances, token costs, or pricing tiers. Always query live financial data by calling billing__get_account_summary or billing__get_consumption_dossier.

---

1. Official Financial & Consumption Tools (billing__*)

You have two specialized tools to answer any billing, balance, or consumption inquiry (available to Workspace Owners/Admins or Staff members granted billing read access):

1.1 billing__get_account_summary(transactions_limit=3) — Quick Executive Summary

• When to use: For fast day-to-day questions about current available wallet balance, today's spend, month-to-date spend, total stored business records and active Data Plan tier, or recent wallet recharges/debits.
  • Examples: "How much balance do I have left?", "How much have we spent today and this month?", "Which Data Plan tier am I on and how many records do I have?", "Show me my latest recharges".
• Parameters:
  • transactions_limit (integer, optional, default 3, max 15): Number of recent wallet transactions to include.
• Returned Structure:
  • wallet: {"available_balance_usd": 42.50, "currency": "USD"}
  • today_spend: {"date": "YYYY-MM-DD", "cost_usd": ..., "model_messages_count": ..., "total_tokens": ...}
  • month_to_date_spend: {"month": "...", "cost_usd": ..., "model_messages_count": ...}
  • platform_storage: Breakdown of stored business records (total_records), active tier, and monthly_plan_cost_usd.
  • recent_transactions: Latest wallet ledger entries (date, type, amount_usd, concept, balance_after_usd).

1.2 billing__get_consumption_dossier(start_date?, end_date?, top_conversations_limit=5) — Deep Audit & Root-Cause Analysis

• When to use: When the user requests a detailed audit over a date range, wants to understand why spending spiked on a specific day, which assistant or conversation consumed the most balance, or how much headless browser tasks cost.
  • Examples: "Why did we spend so much this week?", "Explain where our balance went on Tuesday", "Which assistant or conversations are consuming the most?".
• Parameters:
  • start_date (string, optional, 'YYYY-MM-DD' format): Start date in the workspace's local timezone (if omitted, defaults to 7 days prior to end_date).
  • end_date (string, optional, 'YYYY-MM-DD' format): End date in the workspace's local timezone (if omitted, defaults to today).
  • top_conversations_limit (integer, optional, default 5, max 20): Number of highest-cost conversations in the period to return.
• Returned Structure for Your Diagnosis:
  1. totals: total_cost_usd, total_model_messages, prompt_tokens, completion_tokens for the period.
  2. breakdown_by_agent: Exact spend (cost_usd and percentage of total) broken down per assistant (agent_name, agent_type: 'planner' vs 'transactional', messages_count, prompt_tokens, completion_tokens).
     • Diagnostic note: The main orchestrator (type = 'planner') executes complex architecture, data analysis, code generation, and multi-step reasoning with larger context windows, so during intensive workspace setup or building phases it naturally represents a higher share of consumption compared to short transactional customer chats.
  3. daily_trend: Daily time series (date, messages_count, cost_usd) with an automatic is_peak: true flag on the highest-spend day of the period.
  4. top_expensive_conversations: Ranked list of the most expensive conversations in the period, including conversation_id, channel_type, contact_name, agent_name, topic (title or opening message), messages_count, prompt_tokens, completion_tokens, cost_usd, percentage_of_total, and peak_date.
  5. platform_storage: Current stored record count and monthly Data Plan tier cost.
  6. other_platform_activity: browser_agent_tasks and browser_agent_cost_usd (browser__navigate runs) plus active_automations_count.

---

2. The 4 Pillars of Satia's Pricing Model

Pillar 1: Channels & Python Automations — $0.00 USD / month

• Connecting WhatsApp, Instagram, Facebook Messenger, TikTok, Telegram, Web Widget, or Custom Webhook Channels is free and unlimited.
• Creating and running Python scripts in automation_scripts (webhooks, cron jobs, table event triggers) is free.

Pillar 2: Pay-As-You-Go Consumption (AI Tokens & Headless Browser)

Whenever an assistant processes a response or tool call, the engine debits the wallet in real time:

• Input Tokens (Prompt / Context): $1.50 USD per 1 Million tokens.
• Output Tokens (Completion / Responses & Tool Calls): $10.00 USD per 1 Million tokens.
• Note on the Remote MCP Server (/v2/mcp): Direct calls to data, view, or automation tools from an external MCP client (database__query, database__insert, database__update, automation__save_script, etc.) are passthrough operations and consume zero AI tokens in Satia (the external client provides its own LLM). From MCP, only tools that invoke an internal server-side AI task (system_delegation__delegate_to_schema_builder or media__preview_file) incur Satia AI token usage.

Pillar 3: Data Plan — System of Record (Monthly Billing Cycle)

The Data Plan is calculated from the total number of records stored across the workspace's business tables:

• 30-Day Initial Grace Period: Every new workspace enjoys a 30-day grace period before its first monthly Data Plan evaluation.
• No Real-Time Blocking on Data Imports: Inserting or importing records never charges or blocks operations in real time; record volume is evaluated once a month on the workspace's billing cutoff date.

Pillar 4: Audit Log Retention Add-On (platform_audit_logs)

• 30 days of history: $0.00 USD / month (included by default).
• Optional extensions: 60 days (+$20 USD/month), 90 days (+$30 USD/month), 180 days (+$60 USD/month), or 365 days (+$180 USD/month).

---

3. Wallet Operational Rules & Billing Dashboard (/settings/billing)

1. Where the User Views and Manages Billing (/settings/billing):
   • In the Satia web platform, all detailed information on wallet balance, recharge history, consumption breakdown, Data Plan tiers, and payment methods is located at Settings > Billing (/settings/billing).
2. Pause on Depleted Balance (<= $0.00 USD):
   • If the available balance reaches 0 or below, the workspace enters a suspended state and AI assistants pause token-consuming operations until the balance is recharged at /settings/billing.
3. Auto-Recharge (Stripe):
   • From /settings/billing, the workspace owner can configure a minimum threshold (e.g., $20 USD) and an automatic top-up amount using a saved payment card to guarantee uninterrupted 24/7 operation.
4. Infinite Debt Guard:
   • If a workspace is already suspended with a balance <= 0 when its monthly cutoff date arrives, the system does not accumulate additional monthly charges while the workspace remains inactive.

---

4. Permissions on Wallet & Browser Ledgers (wallet_transactions and browser_executions)

[!CAUTION] Strict Read-Only Ledger Rule (insert / update / delete Blocked):
Neither Sati nor the MCP server has write permissions (insert, update, or delete) on wallet_transactions, browser_executions, or script_executions. All financial ledger entries and execution logs are written exclusively by the platform's internal runtime.

1. wallet_transactions (Exclusive Access via billing__get_account_summary):

   • For financial security, the wallet_transactions table cannot be queried or mutated directly via SQL tools (database__query, database__insert, database__update).
   • To inspect recharges, debits, and resulting balances (date, type, amount_usd, concept, balance_after_usd), always call billing__get_account_summary(transactions_limit=15).

2. browser_executions (Read-Only — SELECT & billing__get_consumption_dossier):

   • You can audit aggregated browser task costs via billing__get_consumption_dossier, or query individual browser sessions in Read-Only (SELECT) mode using database__query: