> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tuturuuu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cost Discovery Inventory

> Every paid provider Tuturuuu depends on, what each costs today, the billing or usage API that can report it, the collector credential it needs and who owns it.

This page is the source list for Admin cost analytics. Each provider row names
the posted-cost source (an invoice or billing export), the usage source (an API
that meters consumption), the collector credential it needs and the
team that owns the account. Credentials are referenced by environment variable
name only.

The reconciliation rules that turn this evidence into Admin numbers live in
`apps/admin/src/lib/admin-costs/README.md`. Reviewed invoices land in
`private.external_provider_invoices`. A root-workspace invoice whose provider,
account and app have a Finance destination in
`private.usage_finance_destinations` posts to that expense category through
`private.post_usage_provider_invoice`; other invoices stay unposted. Run-level
and account-day provider costs land in `private.external_provider_costs`.

## API-reported charges

Snapshot taken 2026-11-21 from read-only provider billing APIs. These are
provider-reported charges, not issued-invoice totals: an open month is still
accruing and a closed month becomes a posted cost only after its invoice is
reconciled. Amounts are USD, rounded to the dollar, and cover the whole
provider account.

| Provider | Scope and source field | Oct 2026 | Nov 2026, through 19 Nov |
| - | - | - | - |
| GitHub | Organization billing usage, `netAmount` | \$32 | \$10 |
| Vercel | Team FOCUS charges, `BilledCost` | \$33 | \$26 |

GitHub's charge is GitHub Secret Protection seats for the organization. Actions
minutes and storage are fully discounted for the public repository, so their
`grossAmount` is list-price exposure rather than spend; it would become spend
if the repository turned private or jobs moved to larger hosted runners.
Self-hosted macOS runners cost machine time outside GitHub billing.

Vercel's charge is the Pro plan plus usage after included credit. Per-project
and per-service detail stays in Admin, not in this public page.

Every other provider has no reported figure yet; see
[Coverage gaps](#coverage-gaps).

## Provider inventory

Owner names the team accountable for the account and its collector credential.
`COST_*` names are proposed collector bindings, each a separate credential
that never shares a token with deploy, runtime or payment paths. The collector
only makes read calls. Where a provider offers no read-only credential (OpenAI
and Anthropic admin keys, the AI Gateway API key), the row says so and the key
is held only by the collector.

| Provider | What we use | Posted cost source | Usage source | Collector credential (scope) | Owner |
| - | - | - | - | - | - |
| Cloudflare | Configured in repo (some held from publication; see the [adoption inventory](https://docs.tuturuuu.com/build/development-tools/oxc-cloudflare-adoption.md)): Workers (gateway, api, about 30 Start apps), Durable Objects (meet-realtime, colab, chat-realtime, abuse-guard, ops-hub, coordination, cron-control, roadmap, deploy-coordinator, devbox-control, mastermind-store, turbo-cache, parley), R2 (meet, parley, lettin, turbo-cache, mail), D1 (lettin), KV (status-api), Queues (ops-hub), Images (meet, parley), Stream, Realtime SFU and TURN, Analytics Engine, Rate Limiting, Email Service, Cloudflare for SaaS, Turnstile, Access | Invoice from the dashboard; Billing API billing history | GraphQL Analytics API per product, priced on each product's billable metric (for example, Images bindings bill unique monthly transformations, so daily request counts cannot be priced directly) | `COST_CLOUDFLARE_API_TOKEN` (account token: Account Analytics Read, Billing Read) | Infrastructure |
| Vercel | Hosting for apps still on Vercel, Analytics, Speed Insights, Blob, Turbo remote cache, AI Gateway | Team invoice | FOCUS charges `GET /v1/billing/charges` (daily rows tagged by project) | `COST_VERCEL_API_TOKEN` (team-scoped token with billing read) | Infrastructure |
| Vercel AI Gateway | Model traffic for Mira, Meet AI and AI Studio | Credit top-up receipts | Dashboard credit balance (manual); the Gateway credit endpoint needs a Gateway API key, not the billing token. `ai_credit_transactions` priced from `ai_gateway_models` is attribution evidence to reconcile against Gateway charges | Invoice import; `COST_AI_GATEWAY_API_KEY` (not read-only: it can also send model requests) if the credit endpoint is adopted | AI platform |
| Supabase | Production, staging and qualify projects in one organization | Organization invoice | Management API project and add-on inventory | `COST_SUPABASE_ACCESS_TOKEN` (scoped token: `organization_projects_read`, `infra_add_ons_read`) | Infrastructure |
| GitHub | Actions (hosted Linux, macOS and Windows), Actions storage, Git LFS, Secret Protection | Organization receipt or invoice | `GET /organizations/{org}/settings/billing/usage` (daily SKU rows with gross, discount and provisional net amounts) | `COST_GITHUB_TOKEN` (fine-grained token: organization Administration read) | Infrastructure |
| Google Gemini and Vertex AI | Mira, Meet notes and live assistants, AI Studio | Google Cloud invoice | Cloud Billing detailed export to BigQuery | `COST_GCP_BILLING_EXPORT_SA` (service account: BigQuery Data Viewer on the export dataset, BigQuery Job User) | AI platform |
| Google Cloud and Firebase | OAuth, Calendar, Play Integrity, Firebase Cloud Messaging | Google Cloud invoice | Same billing export | `COST_GCP_BILLING_EXPORT_SA` | Infrastructure |
| OpenAI | ChatGPT provider, speech evaluation | Organization invoice | Costs API `GET /v1/organization/costs` | `COST_OPENAI_ADMIN_KEY` (admin key; no read-only variant, so it lives only in the collector) | AI platform |
| Anthropic | Direct provider in `packages/ai` | Console invoice | Usage and Cost Admin API (the `cost_report` endpoint is legacy; use the current analytics endpoints) | `COST_ANTHROPIC_ADMIN_KEY` (admin key; same isolation) | AI platform |
| Modal | Discord bot and speech-to-text jobs | Workspace invoice | None used | Invoice import | AI platform |
| Supermemory | Mira memory | Invoice | None used | Invoice import | AI platform |
| AWS | SES sending and inbound mail, S3 | AWS invoice | Cost Explorer `GetCostAndUsage` (each request is billed, so collect once a day) | `COST_AWS_ACCESS_KEY_ID`, `COST_AWS_SECRET_ACCESS_KEY` (IAM `ce:GetCostAndUsage` only) | Infrastructure |
| Upstash | Rate-limit Redis | Invoice | None used | Invoice import | Infrastructure |
| Polar | Billing platform fees | Ledger fee entries | Orders API | Finance ledger export by default. A `COST_POLAR_ACCESS_TOKEN` with `orders:read` can also generate invoices, so it is not read-only | Finance |
| SePay | Vietnamese payments | Statement | None used | Invoice import | Finance |
| Apple Developer Program | iOS and macOS distribution | Annual membership receipt | None | Finance recurring entry | Mobile release |
| Google Play Console | Android distribution | One-time registration receipt | None | Finance entry | Mobile release |
| Code signing | Windows signing certificate | Issuer invoice | None | Finance recurring entry | Mobile release |
| Domains and DNS | `tuturuuu.com` and other registered domains | Registrar invoices | None | Invoice import | Infrastructure |
| Google Workspace | Staff mailboxes | Admin console invoice | Seat counts | Invoice import | Finance |
| Developer SaaS | Mintlify, CodeRabbit, Codecov | Plan invoices, if any | None | Invoice import | Infrastructure |

Not in use and not costed: Hyperdrive, Workers AI and Vectorize have no
binding; Sentry, PostHog, Stripe, Resend, Postmark and SendGrid have no call
sites. Groq, Mistral, xAI, DeepSeek, Perplexity, Fireworks, Together, DeepInfra
and Cohere SDKs are dependencies only, reached through AI Gateway model IDs, so
their spend appears in Gateway credits.

## Collector

The `provider-cost-collection` job in Cron Control
(`apps/cron-control/src/processors/provider-cost-collection.ts`) collects GitHub
and Vercel billing days on Cloudflare, following the
[backend ownership guard](https://github.com/tutur3u/platform/blob/main/docs-internal/build/devops/cloudflare-backend-ownership.mdx).
It runs daily at 03:17 UTC and stays off until `CRON_CONTROL_ENABLED_JOBS`
names it. A source runs only when both of its Worker secrets are set:

| Source | Worker secrets | Request per provider-day |
| - | - | - |
| GitHub | `COST_GITHUB_ORG`, `COST_GITHUB_TOKEN` | One billing usage request filtered to the day, response capped at 4 MB |
| Vercel | `COST_VERCEL_TEAM_ID`, `COST_VERCEL_API_TOKEN` | One FOCUS charges request for the UTC day, streamed, capped at 48 MB and 60,000 rows |

Each run plans at most three provider-days per source with
`private.plan_provider_cost_days`: the two most recent completed UTC days,
which providers restate while usage settles, and the oldest day never
collected in the last 90 days. The Cron Ledger stop fence is checked before
every provider call. Before each call the collector claims the day with
`private.claim_provider_cost_day`, which counts a durable attempt; a complete
collection resets the count. A day that fails is left for the next daily run
rather than retried in the same run, and a day that reaches three attempts
without a complete collection becomes `budget_exhausted`. A restart or a
`degraded` run therefore cannot keep paying for the same failing day. A
claimed day stays eligible for seven days after it leaves the 90-day window,
so a day at the edge keeps its remaining attempts. The fence is checked again
after each claim. A provider request that hits its own 45-second budget fails
that day and skips the rest of that source for the run, so the next source
still gets its time. A claim or write the database rejects fails only that
day; one whose commit cannot be confirmed ends the run as `unknown`.

`private.record_provider_cost_day` replaces one provider-day atomically in
`private.provider_cost_lines`, aggregated by service, SKU, app, environment
and unit. An older snapshot never overwrites a newer one. Claims, recordings
and exhaustion markers for a day take the same transaction lock, so a
concurrent marker cannot be overwritten by a recording. Vercel rows belong
to the day their charge period starts; a UTC window also returns the
previous day's row, which the collector skips.

A day whose response exceeds its cap is also marked `budget_exhausted` in
`private.provider_cost_collection_days`. That state is terminal: later runs
neither plan nor overwrite the day, so an oversized window is never paid for
twice. After raising a cap or narrowing the query, delete the day's row to
collect it again. The job reports `degraded` while any day in the run was
exhausted or failed.

Lines record the provider's list amount (GitHub `grossAmount`, Vercel
`ListCost`, left empty when Vercel omits it) and its billed amount
(`netAmount`, `BilledCost`). Vercel lines are keyed by `SkuId`. A day with a
missing or non-numeric billed amount, or a row without a valid usage date,
fails instead of being recorded as zero or as a partial day.
Both amounts are provisional until the month's invoice reconciles them.
Failure logs carry only the provider, day, failure category and HTTP status,
never response content.

The Vercel charges endpoint returned about 620,000 daily rows (about 480 MB)
for four months, which is why the collector requests one day per call.

Other providers keep invoice import until their collector credential and
source exist. A future source with paginated, billed requests (AWS Cost
Explorer bills each page) also caps its pages per day and marks the day
exhausted when the cap is reached.

## Admin Costs page

Admin → Monitoring → Costs (`/[wsId]/costs` in `apps/admin`) needs
both `view_infrastructure` and `view_finance_stats`, the same pair as the
invoice summary on Observability. Its data comes from
`GET /api/v1/infrastructure/costs`; each source loads independently, so an
unavailable source shows as unavailable instead of as zero.

| Section | Source and rule |
| - | - |
| Summary | Billed month to date, forecast and last month for the UTC month of the request; spend per monthly active user (an estimate, below) |
| Anomalies | A provider's last complete day billed above 3× the median of its collected days among the previous 14 (and at least $1), or a forecast above 1.5× last month (and at least $5 more) when last month and this month so far are fully collected |
| Daily spend | Billed charges per provider per day |
| Breakdown | Last month, month to date and forecast per provider, app and environment |
| Provider invoices | Reviewed root-workspace invoices from `private.get_root_provider_invoice_postings`, each linked to the Finance transaction it posted to, or marked not posted |
| Recorded provider costs | Run-level costs apps record in `private.external_provider_costs` |
| Data coverage | Collected days, budget-exhausted days and inventory providers without a collector |

One request timestamp fixes the reporting month (the UTC month containing
it) and the data cutoff (the last complete UTC day), so on the first of a
month the page forecasts the new month from zero elapsed days.
`private.get_provider_cost_complete_days` lists completed collection days
per account. A provider-day counts as complete only when every account the
provider has collected completed it; a complete day without charge rows is a
measured zero, and any other day is missing, not zero. Daily rows are read
in pages of 1,000; more than 20,000 rows marks the source unavailable rather
than showing a truncated total.

Each summary total is checked against completed days for its own period:
month to date, last month, and the forecast's inputs (month to date, the
run-rate window, and any last-month amount it carries forward). A total
with an uncollected day is labeled partial. With no verified collection at
all, for example when only invoices exist, the totals read "Not measured"
instead of \$0.

Services are classified once per provider and service, so every breakdown
tab rolls up the same forecast. A service charged on at least three of the
last 14 days is variable: its average over the collected days of the last
seven is extrapolated to the rest of the month, using charges from complete
days only, and the forecast is marked partial when any of those seven days
was not collected. Other services are fixed charges (plan fees, seats),
projected per service, app and environment: once charged this month they
keep their month-to-date amount, even when a credit nets it to zero, and
before that they use last month's amount. A closed month forecasts its actuals. The rules
live in `apps/admin/src/lib/admin-costs/trends.ts`.

Spend per monthly active user divides collected billed spend over the last
30 complete UTC days by `get_mau_count`, which counts users active in the 30
days up to the request, including the current day. The windows differ by
that day and only collected providers count, so the page labels it an
estimate.

The Costs navigation item appears only to root members with both
permissions, matching the page and API.

## Budget alerts

Monthly budgets live in `private.provider_cost_budgets`, one row per
provider (`github`, `vercel`, `cloudflare`) or `total` for every collected
provider. With no rows, nothing alerts. Set or clear a budget with
`private.set_provider_cost_budget(provider, monthly_limit_usd, warn_ratio)`
(service role only); a null limit clears it, and `warn_ratio` defaults to 0.8.

After collecting, each `provider-cost-collection` run calls
`private.dispatch_provider_cost_budget_alerts` for the last complete UTC day.
For each budget it projects the billed month to date linearly over the month
and alerts once per month and level. On the first two days of a month, when
the collector can still restate the previous month, that month is evaluated
again through its last day so a late charge still raises its alert:

| Level | Condition | Priority |
| - | - | - |
| `forecast` | The projection reaches `warn_ratio` of the limit | High |
| `exceeded` | The billed month to date reaches the limit | Urgent |

A client-side rejection degrades the run and the next run evaluates again;
a server or gateway error, or a response that cannot be read, may follow a
committed dispatch, so it ends the run as `unknown`. Dispatches take a
transaction lock, so overlapping runs evaluate one at a time.

Alerts go through `private.send_root_operator_alert`, the shared sender for
platform operator alerts. It records each dedupe key once in
`private.root_operator_alerts`, then calls `public.create_notification` for
up to 50 root workspace members holding every required permission (budgets
require `view_finance_stats` and `view_infrastructure`, the same pair as the
Costs page). Recipients get the web inbox, email and push according to their
notification preferences; the existing `web-notification-batches` job
delivers email and push. Only created notifications count. When none is
created, because no member qualifies or every recipient has turned off all
channels, the key is released and a later run can deliver it. Notifications
carry the provider, month, level and amounts but no link: the inbox, push and
email surfaces do not yet route this kind to the Costs page.

Mastermind and Mira have no server-side path for these alerts. Mastermind
push events carry only inbox item IDs from the fleet hub, and Mira's
proactive execution is inactive, so both are left for a later sender behind
the same function.

## Unit economics denominators

| Unit | Denominator source |
| - | - |
| Active workspace or user | Session and engagement sources used by the Executive overview |
| AI request | `ai_credit_transactions`, `private.ai_studio_usage`, `private.ai_live_sessions` |
| Meet minute | `public.meet_ai_sessions`, `meet_ai_chunks.duration_seconds`, `private.meet_attendance_sessions`, presence intervals from `packages/realtime/src/meet/room-budget.ts` |
| Metered workspace usage | `private.usage_meter_periods` (`sandbox_seconds`, `participant_seconds`, `stored_bytes`, `transfer_bytes`) |

`attributedUnitCost` divides posted, reconciled cost attributed to a target by
a complete denominator for the same provider, account, target and window.
Estimates cannot feed it; an estimate-based unit cost must be labeled as an
estimate and computed separately.

## Coverage gaps

These need a credential or an invoice before Admin can show a figure:

* Cloudflare: `COST_CLOUDFLARE_API_TOKEN`.
* Supabase: `COST_SUPABASE_ACCESS_TOKEN` for inventory, and organization
  invoices imported through the Finance invoice flow.
* Google Cloud, Gemini, Vertex and Firebase: billing export to BigQuery enabled
  on the billing account, then `COST_GCP_BILLING_EXPORT_SA`.
* OpenAI and Anthropic: `COST_OPENAI_ADMIN_KEY`, `COST_ANTHROPIC_ADMIN_KEY`.
* Vercel AI Gateway: credit top-up receipts through the Finance invoice flow.
* Polar: the Finance ledger export.
* AWS: `COST_AWS_ACCESS_KEY_ID` and `COST_AWS_SECRET_ACCESS_KEY`.
* Invoice-only providers (Modal, Supermemory, Upstash, SePay, Apple, Google
  Play, code signing, domains, Google Workspace, developer SaaS): import each
  invoice through the Finance invoice flow.

The AI executions cost view prices tokens per million from a fixed Gemini rate
table in `ai/executions/utils/cost-calculator.ts` (web and workspace). It is a
rate-model estimate for that page only and is not a provider cost source.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.