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.
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.
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.
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
Theprovider-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.
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:
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.
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 inprivate.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:
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
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_TOKENfor 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_IDandCOST_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.
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.