Skip to content

Bot-flow Gemini AI usage metering

ConnectGain meters Gemini token usage for bot flows so each organization can see estimated cost per flow. Google does not provide a multi-tenant “per org / per bot flow” billing API — usage is captured from each Gemini response’s usageMetadata at the request boundary (including thoughtsTokenCount).

Google AI Studio / Cloud Billing show invoice $ for a GCP project only. They cannot attribute spend to ConnectGain orgs or bot flows (and ConnectGain cannot read customer BYOK billing accounts). Request-boundary metering is the source of truth for the dashboard.

What is metered (V1)

Source How
AI Response nodes with Google/Gemini n8n HTTP → gemini-proxy edge function → Gemini API (exact usageMetadata)
AI Agent nodes with Google/Gemini n8n lmChatGoogleGemini → gemini-meter transparent proxy (exact usageMetadata per LLM call, including tool-loop iterations + thinking tokens)
RAG System nodes with Google/Gemini LLM Same gemini-meter path as AI Agent (embeddings still call Google directly)
Smart Query nodes n8n-flow-callback smart_query → Gemini generateContent for NL filter extraction → recordAiUsage with diagnostic metadata (exact usageMetadata, or text-length estimate)
Flow voice STT (trigger transcribeVoice) the platform via n8n-trigger

When gemini-meter / gemini-proxy cannot be used, a best-effort callback path may estimate tokens from text length (~4 chars/token). Label those as Estimated.

Everything else is metered too, since callGemini / callChat now record centrally — see Org-wide AI consumption for the full coverage map and the short list of deliberate exclusions.

Call Intelligence and Meetings now write into the same ai_usage_events ledger, tagged feature = 'call_intelligence' | 'meetings' and priced against whichever vendor served the call — see Org-wide AI consumption for the per-feature breakdown at /billing/ai-usage.

Data model

  • ai_usage_events — append-only per-invocation log (org-scoped RLS SELECT)
  • metadata JSONB — short diagnostic summary for AI Logs (e.g. Smart Query search_text, category, price band, result_count, truncated input_preview). Not full prompts/responses.
  • bot_flow_token_usage — monthly rollup per (organization_id, bot_flow_id, month_year)
  • RPC increment_bot_flow_tokens — atomic upsert (service_role only)

Estimated USD is computed at write time from the platform (Google Gemini API Standard-tier rates from ai.google.dev/pricing, last verified 2026-08-05). Thinking tokens are billed at the output rate. The UI labels this as Estimated cost (tokens × published rates; Google’s invoice remains authoritative for the GCP project that owns the API key). Existing rows keep the cost stored at write time; redeploy edge functions after rate updates so new events use the latest table.

BYOK vs platform

  • Org BYOK (organizations.settings.ai_provider): Google bills the org’s Google account. ConnectGain still shows estimated cost for visibility.
  • Node API key: key is stored in the n8n googlePalmApi credential (Agent/RAG) or sent to gemini-proxy in the JSON body (AI Response), never embedded in public workflow URLs without auth.
  • Org BYOK keys for AI Response are resolved server-side by gemini-proxy.
  • AI Agent / RAG Google credentials use host = gemini-meter path that embeds org/flow/node + N8N_CALLBACK_SECRET so every SDK call is attributed and authenticated.

Required ops: redeploy flows

Existing published workflows still call Gemini directly (or use callback estimates) until they are redeployed (Publish / Redeploy in the flow builder). After deploying this change:

  1. Apply migration 20260805183000_bot_flow_ai_token_usage.sql (if not already)
  2. Deploy edge functions gemini-meter, gemini-proxy, and updated n8n-deploy-flow
  3. Redeploy each published flow that uses Google AI Response, AI Agent, or RAG System nodes

Historical usage before redeploy cannot be backfilled from Google for per-flow attribution.

Org dashboard

  • Route: /flows/ai-usage (feature gate bot_flows) — cost rollups (totals, per-flow table, recent events)
  • Route: /flows/ai-logs (feature gate bot_flows) — diagnostic call log (filters by flow / node type / period; expandable rows show Smart Query extraction summary + tokens)
  • Access: OWNER / ADMIN only
  • Periods: Day / Week (ISO week, UTC) / Month
  • Day & week aggregate from ai_usage_events; month uses bot_flow_token_usage rollup on the Usage page
  • AI Logs always reads from ai_usage_events (including metadata)

Security

  • gemini-proxy uses the same N8N_CALLBACK_SECRET / x-n8n-secret pattern as n8n-flow-callback
  • gemini-meter authenticates via the secret segment in the credential host path (constant-time compare); JWT verification is off (n8n calls it)
  • Tables: authenticated SELECT within org; writes are service_role only