SupabaseTenancy and placementguide
Per-project cost attribution on Supabase
Two different situations need the same answer - “what did this project cost?” - and neither gets it from a dashboard:
- A platform billing its users for per-tenant backends (one Supabase project per tenant).
- One company that consolidated many projects into a single org for a unified bill and lost per-project visibility - internal chargeback, showback, or a cost review before a commit decision.
The first situation presumes the one-project-per-tenant answer to the Tenant placement decision; this guide prices that answer.
There is no org-scoped billing read on the Management API. What exists is enough to build attribution yourself, in three layers. You need a Pro org, a PAT, and the projects you want to attribute. Unless a row says otherwise, numbers were measured against the live API on 2026-08-17/18 on a Pro org; later runs and other plans are dated where they appear; the invoice structure was read off a Pro-plan invoice.
Layer 1 - the invoice is the settlement layer, and it already itemises per project ref
Section titled “Layer 1 - the invoice is the settlement layer, and it already itemises per project ref”Every usage-based line on the invoice breaks out per 20-char project ref with quantity and rate: compute hours, branching compute, disk GB-hrs, point-in-time recovery, cached and uncached egress, storage GB-hrs, custom domains. The per-project usage data is on the invoice itself - anonymously (refs, not names), but present.
- The per-ref numbers are gross at list price. Supabase’s invoice guide says a paid plan’s usage quota is declared as a discount on the invoice, and its example deducts the $10 Compute Credits from the combined compute fees of two projects ($10 each, $10 after the deduction).1 Net cost per project requires an allocation rule Supabase does not supply - and with a credits pack, the pooled share can be the majority of the spend.
- A monthly PDF is not a dataset. It answers no trend, what-if, or idle-detection question, and it exists only after the month closes. Layer 2 builds the missing part: a queryable hourly time series per ref.
The plan fee, monthly active users (MAU), function invocations, realtime messages and peak connections, and discounts do not itemise per project. These are org-level aggregates with no project dimension, so they need an allocation policy (equal split, weighted by another signal, or eaten by the platform); no tooling can recover per-project data for them.
The monthly reconciliation maps ref -> owner, then applies the policy to the pooled lines.
Layer 2 - between invoices, the estimator
Section titled “Layer 2 - between invoices, the estimator”A control-plane poller builds the same picture hourly from public endpoints. Measured behaviour of each signal:
- Compute cost per project:
GET /v1/projects/{ref}/billing/addonsreturns the selected compute SKU, and cost is SKU rate x hours at the invoice’s own rates (Micro measured at $0.01344/hr there). On Pro nothing suspends (pause is refused with400 Project is not free-tier, measured); Team readsproject_pausing: falseon the entitlements endpoint (2026-08-03) and was not asked to pause, so compute-hours are provisioned wall time on both. On a Free org the data API answersHTTP 540 Project pausedimmediately after a manual pause, and two auto-paused free-plan projects had no DNS record for their hostname (read 2026-09-23). Readstatuson every sweep and count hours only while the project is notINACTIVE. That count is an upper bound on a Nano project with scale-to-zero pricing, which Supabase offers to select customers by arrangement and only on Nano (Micro and larger cannot scale to zero).2 There the billed compute follows the terms of that arrangement rather than wall time, and the project’sstatusdoes not tell you what was billed; reconcile against the invoice (layer 1). Storage is accounted separately from compute, so do not model storage as zero because compute has stopped. This corpus has not measured storage accounting across the compute states. - Database size, exact:
pg_database_size()overPOST /v1/projects/{ref}/database/query. The deltas compress: arepeat()-generated 8 MB payload moved the measured size by ~180 KB because TOAST compresses repetitive text. Use random payloads when validating your own pipeline. - Storage bytes, exact: the Storage object listing matched an uploaded 262144-byte object to the byte.
- Request volumes per service, exact at minute-scale lag:
GET /v1/projects/{ref}/analytics/endpoints/usage.api-counts?interval=15minreturned 13 for exactly 13 REST requests sent, visible after 61 s. That lag is fine for billing rollups and too slow for real-time enforcement. - No per-service egress bytes. The per-project
Prometheus endpoint (326-328 metric families via a plain PAT) is
infrastructure-grade -
node_,pg_,pgbouncer_families with host-level network counters only. Per-project egress per service exists on the invoice per ref and nowhere in the public per-project API. If egress allocation matters between invoices, it has to come from layer 3.
At fleet scale the poller is bound by the Management API rate limit,
documented as 120 requests per minute per user, per project or organization,
per endpoint, with usage.api-counts held to 30 per minute.3
x-ratelimit-remaining is on every response (measured), so pace by the header
rather than a guessed constant.
Layer 3 - real time: meter at your own gateway
Section titled “Layer 3 - real time: meter at your own gateway”If requests to tenant projects transit your own ingress (a proxy, a
gateway, an edge worker), metering there is exact and immediate, and the
gateway can also narrow the credentials. Measured end-to-end against a
live credential-proxy gateway (PAT stored server-side, scoped keys minted
per project), a key allowed metrics:read on exactly one project scraped
its metrics through the gateway (200, 278 families) while the same key got 403 on an
unclassified path and on any other project, and every proxied call was
visible in an audit feed within ~1 s. Each scraper gets a scoped, revocable
key instead of an account-wide classic PAT.
Direct Postgres connections bypass any gateway - they are covered by layers 1 and 2 instead.
The build
Section titled “The build”- A
tenant/owner -> project_refmap in your control-plane database, written at provision time. - An hourly row per project: compute SKU, status, database size, storage
bytes, request-count deltas. At a fleet of a couple of hundred projects
this is a few hundred API calls per sweep, inside the rate budget if you
pace by
x-ratelimit-remaining. - A monthly join of that table against the invoice’s per-ref lines.
If the join disagrees, the invoice wins because it is the settlement document; the estimator shows the month before it closes.
One org, many business units
Section titled “One org, many business units”The same machinery answers a second question: several business units share one organization and one bill, and each unit needs its own cost. The platform records no attribution - in the public v1 spec the project object carries no creator, tag, label or metadata field, on the organization listing or the project detail4 - so the owner map has to be written by whoever creates the project. The pieces:
- The create response is the write path.
POST /v1/projectsreturns the new project,refincluded, in its201body,4 so the service that creates a project recordsref -> unitfrom that response. Writing a pending row before the call, and completing it on the response, keeps a crash between the two recoverable (design choice). - A name can change after create.
PATCH /v1/projects/{ref}takes a newname,4 so a unit prefix in the name can drift from the map. - The sweep reads the organization listing.
GET /v1/organizations/{slug}/projectspages withlimit(at most 100) andoffsetand reportspagination.count.4 Diffing it against the map puts any project created outside the write path into anunattributedbucket instead of losing it. How soon a new ref appears in the listing was not measured. - Branches carry their own ref. In the spec the parent link is on the
parent-scoped branch reads,
GET /v1/projects/{ref}/branchesandGET /v1/projects/{ref}/branches/{name}(parent_project_refbeside the branch’sproject_ref);GET /v1/branches/{branch_id_or_ref}describes connection details with no parent field, and the organization listing marks a row withis_branchbut names no parent.4 So the sweep walks each parent’s branches and assigns the parent’s unit. Whether a branch ref appears in the organization listing was not measured. - Deleted refs still turn up on the invoice. On the Pro-plan invoice reconciled in M07 29 of its 32 refs had been deleted by reconciliation time, which is why the map keeps every row. Giving rows a validity period, so that moving a project between units does not rewrite past months, is a design choice.
- Role assignment over the API is Team and Enterprise. Per the Access
Control guide, only Owner and Administrator can create projects, a
project-scoped member cannot view, access or see other projects in the
dashboard, an organization-level role covers current and future projects,
and project-scoped roles are a Team and Enterprise
feature.5 A project-scoped invite names a single
project; more projects are added in the dashboard after the user accepts.
On the Management API,
PATCH /v2/organizations/{slug}/members/{user_id}/rolesassigns an org-wide role, or a project-scoped one whenprojectsis given, and its OpenAPI entry carriesx-allowed-plans: ["Team", "Enterprise"].6 So on Team or Enterprise the service that creates a project can also grant its unit’s people access to it; that grant has not been measured. Pro has no project-scoped roles to grant. - The audit log names the creating token. The Platform Audit Logs guide
lists the actor and token type on each entry; the logs are read in the
dashboard, which has no export, or streamed to an external destination
through Audit Log Drains.7 The open-source dashboard
reads the log from
/platform/organizations/{slug}/audit, and its response type declarestoken_type,token_hash,token_alias(the token’s name as shown in the dashboard) andoauth_app_id/oauth_app_namefor each actor.8 A PAT is refused on that route with401 JWT could not be decodedwhile the same PAT answers200on/v1(Team organization, BA06). The audit log is a security record of who created what; attribution comes from the map and the usage join, and anunattributedref is closed by fixing the write path or the sweep that missed it.
On-demand creation and the sweep run under one automation user whose budget
is cumulative across that user’s PATs (L01b, below); the counter is
documented as per user, per project or organization, and per
endpoint,3 so how creates, sweeps and per-parent branch
reads share it was not measured. Because the measured counter is per user, one
automation user per unit should give each its own budget; two users were
not measured. The monthly check is the same join as above, extended:
unit totals plus unattributed plus the allocated pooled lines equal the
invoice total.
The reference implementation
Section titled “The reference implementation”Every mechanism in this guide runs as a tested module in the public
supabase-lab repo9
(experiments/usage-metering/), each gated by an acceptance probe against
the live platform:
| Module | What it proves | Measured |
|---|---|---|
| M03 | The estimator, read-only against a live org: enumerate -> SKU -> cost table | 3 projects at $9.81/mo each, $29.43 org monthly compute - matching the invoice’s own rate card |
| M04 | Per-key metering at a credential-proxy gateway is exact: one scoped key per tenant = a per-tenant usage ledger | 7 proxied calls -> exactly 7 events, 5 -> 5, correct project ref and status on every event |
| M05 | One project can hold the tenant map + rollups including itself (self-inclusion), and per-tenant attribution inside a shared schema is exact from SQL | 4/4 rows inserted via the store’s own PostgREST; t-a 100 rows / 100,400 bytes vs t-b 25 / 25,100 via pg_column_size |
| M06 | The rollup is idempotent under re-flush and late events | Re-flush identical; a late event into a closed window moves its total by exactly its quantity; duplicate idempotency keys rejected; other windows untouched |
| M07 | The invoice parses into a dataset and reconciles against the live org | 91 per-ref lines, 32 refs, 3 matched by name, 29 deleted since invoice; standing projects billed 592/600 h (98.7% of the window) |
What to do about it
Section titled “What to do about it”A practice with no module id is a design choice rather than a result: the allocation policy for pooled lines and the sweep cadence are choices, and nothing measures which cadence billing precision needs.
| Practice | Evidence | Module |
|---|---|---|
Never delete the ref -> owner row when the project is deleted; keep it indefinitely. | The invoice arrives after the month closes and itemises refs that no longer exist: on the reconciled invoice 29 of 32 refs had been deleted since, and only 3 could be matched by name. | usage-metering M07 |
Make the hourly rollup idempotent: key each row by (ref, hour) and upsert; recompute a closed window when a late event lands. | Gateway events need their own idempotency key so duplicates are rejected. The recomputed total moves by exactly the late event’s quantity and other windows stay untouched. | usage-metering M06 |
Read status on every sweep and count compute hours only outside INACTIVE. | Pro refuses a pause (400 Project is not free-tier, measured); Team reads project_pausing: false on the entitlements endpoint (2026-08-03) and was not asked to pause; a Free org pauses and restores (data API HTTP 540 Project paused). Even on Pro the hours are not the full window: standing projects on the reconciled invoice billed 592 of 600 h (98.7 %). | instance-sizing I04; usage-metering M07 |
| Run the poller under a dedicated automation user. | The 120-per-minute budget is per user across PATs (each token’s x-ratelimit-remaining drops on the other’s calls), so sharing a human’s user starves both. | rate-limits L01, L01b (2026-08-17/18) |
| Treat a non-JSON body as a 429. | The measured breach on a scoped read is a JSON ThrottlerException with retry-after: 60; the non-JSON body is a different response, the edge layer’s HTML page, seen under aggressive polling of other endpoints and not reproduced by the 15-cell burst matrix of 2026-10-13. | rate-limits L01, L01b (2026-08-17/18), L02 (2026-10-13) |
Expose the metering schema to PostgREST with PATCH /v1/projects/{ref}/postgrest, or keep the store in public; never set db_schema: "". | PostgREST serves only the configured db-schemas (default public), so a request for a custom schema is refused with 406 PGRST106 until db_schema includes it. The empty value wedges PostgREST (503 PGRST002 within 6-8 s). | usage-metering M05; supabase-lab AGENTS.md, http-tier-lockdown (2026-08-02) |
Sweep GET /v1/organizations/{slug}/projects page by page and diff it against the map. | Refs missing from the map go to an unattributed bucket (design choice). The listing pages with limit (at most 100) and offset; how soon a new ref appears was not measured. | none - public v1 spec4 |
| Attribute branch refs through the parent-scoped branch reads. | Of the reads in the spec, only GET /v1/projects/{ref}/branches and GET /v1/projects/{ref}/branches/{name} carry parent_project_ref; GET /v1/branches/{branch_id_or_ref} has no parent field and the organization listing marks a branch with is_branch and names no parent. Not measured. | none - public v1 spec |
| Keep the audit log out of the attribution pipeline; use it for security review. | The guide documents dashboard viewing with no export, and Audit Log Drains for streaming; a PAT gets 401 on the dashboard’s audit route. Attribution rests on the map written at create time and the sweep. | bu-attribution BA06 (2026-10-02); Platform Audit Logs guide |
| On Team or Enterprise, grant a new project’s members with the v2 roles endpoint. | PATCH /v2/organizations/{slug}/members/{user_id}/roles assigns a project-scoped role when projects is given and is listed for Team and Enterprise (x-allowed-plans); not measured. Pro has no project-scoped roles. In the dashboard a project-scoped invite names one project and more are added after acceptance. | none - public v2 spec6; Access Control guide |
Record ref -> unit from the create response, never from the project name. | PATCH /v1/projects/{ref} takes a new name, and the project object has no creator or tag field. | none - public v1 spec |
For tenants on a shared project, attribute bytes per tenant from SQL: sum(pg_column_size(t.*)) grouped by tenant_id, hourly. | The measured readings were 100 rows / 100,400 bytes against 25 / 25,100. The invoice and billing/addons are per project; inside one project this is the only measured attribution signal. | usage-metering M05 |
| For metrics scrapers without a gateway, use a scoped PAT from a dedicated automation user | The token is limited to the projects being metered. The per-project Prometheus endpoint accepts a plain PAT (200, 326-328 families). a probe found no scope endpoint on /v1 (2026-08-03; later codified as F03); the Personal Access Tokens guide now documents scoped tokens created in the dashboard, limited to chosen organizations, projects and permissions.10 A scoped token on the metrics endpoint was not measured. | usage-metering M01c; platform-facts F03 |
When validating usage.api-counts, anchor the read to the last request sent and send Prefer: count=exact. | The first run’s 10 of 12 was warm-up requests confounding the count, and the corrected run read 13 of 13 after 61 s. | usage-metering M01b (2026-08-17) and the 2026-08-18 re-run |
Verification
Section titled “Verification”Validate the layer-2 estimator against your own org using only the endpoints this doc measured, one pass per project ref:
- Compute SKU:
GET /v1/projects/{ref}/billing/addonsreturns the selected compute SKU; multiply by the invoice’s own rates for that SKU’s hours. - Database size:
pg_database_size()overPOST /v1/projects/{ref}/database/query. To confirm the deltas are real, grow a table with random bytes, notrepeat()-generated, because TOAST compresses the latter. - Storage bytes: a Storage object listing should match an uploaded object to the byte.
- Request volume:
GET /v1/projects/{ref}/analytics/endpoints/usage.api-counts?interval=15minshould return exactly the requests you sent, visible after 61 s. - Pace the sweep by
x-ratelimit-remainingon every response rather than a fixed interval.
M03 in the module table is the read-only reference implementation of this pass against a live org.
Gotchas and lessons learned
Section titled “Gotchas and lessons learned”PostgREST exposes only the configured db-schemas (default public), so
a request for a custom metering schema gets 406 PGRST106 until
configured. The same ref can appear in multiple invoice sections (compute
and branching compute), so a production parser tracks section headers.
What this does not give you
Section titled “What this does not give you”- Attribution of pooled org-level lines (plan fee, MAU, functions, realtime, discounts) - a policy decision, never data.
- History before you start polling - the estimator sees forward from when it is built; the invoice archive is the only backwards view.
- Enforcement - the Spend Cap is an organization-wide switch on the Pro plan: on, usage of a covered item past the plan’s quota is disallowed until the next billing cycle. Compute is not a covered item, and the cap sets no budget for a specific item and sends no notifications.11 Detecting a runaway project and acting on it is your own poll-and-act loop on layer 2/3 signals.
Verified / tested
Section titled “Verified / tested”| Claim | How it was checked |
|---|---|
| Invoice itemises usage lines per project ref; plan/MAU/functions/realtime/discounts do not itemise | Read off a Pro-plan invoice, 2026-08 |
Compute SKU per project via billing/addons; pause refused on Pro | Measured 2026-08-17/18 - 400 Project is not free-tier |
| Micro rate $0.01344/hr | Read off the invoice’s compute line |
pg_database_size + Storage listing exact | Measured 2026-08-17 - byte-exact storage; TOAST compression caveat on database size |
usage.api-counts exact (13/13) at 61 s lag | Measured 2026-08-17/18, reproduced after accounting fix |
| No per-service egress bytes in the per-project API | Metrics endpoint enumerated 2026-08-18 - node_/pg_/pgbouncer_ families only |
| Scoped-key gateway metering: 200/278 families, 403 deny-by-default, ~1 s audit | Measured 2026-08-18 against a live credential-proxy deployment |
~120 req/min per user per scope on the route measured, headers on every response; usage.api-counts is held to 30/min | Measured 2026-08-17 - burst to the JSON 429 boundary; the 30/min limit read from the Management API introduction, 2026-11-13 |
Create returns the ref in the 201 body; the organization listing pages at a limit of at most 100 | Documented in the public v1 spec (read 2026-11-13); not measured |
| No creator/tag/label/metadata field on the project; names mutable | Documented in the public v1 spec (read 2026-11-13); not measured |
Of the branch reads, parent link only on the parent-scoped reads (/projects/{ref}/branches and /projects/{ref}/branches/{name}) | Documented in the public v1 spec (read 2026-11-13); not measured |
| Member role assignment over the API is Team and Enterprise | Documented in the public v2 spec (x-allowed-plans, read 2026-11-13); not measured |
| A project-scoped member cannot create projects or see other units’ projects | Documented for the dashboard (Access Control guide); not measured on the Management API |
| A PAT cannot read the organization audit log | Measured 2026-10-02 on a Team org: 401 on the dashboard route, 200 on /v1 (BA06) |
File reference
Section titled “File reference”No repo files are edited: this guide defines a control plane you build. The artefacts it asks for:
| Artefact | What it is |
|---|---|
| The tenant map | tenant/owner -> project_ref, written at provision time; module M05 keeps it in a project’s own schema |
| The hourly usage rows | Compute SKU, status, database size, storage bytes and request-count deltas per project, one row per project per hour |
| The monthly join | That usage table joined against the invoice’s per-ref lines |
| The scoped-key gateway | One key per tenant, metering every proxied call (M04) |
experiments/usage-metering/ | The tested reference implementation in supabase-lab, M03-M07 |
Modules
Section titled “Modules”| Module | Experiment | Test | Artifact |
|---|---|---|---|
| BA06 | bu-attribution | ba06-audit-log-access.ts | none published |
| F03 | platform-facts | f03-pat-scope.ts | none published |
| I04 | instance-sizing | i04-free-org.ts | run-2026-08-18T04-43-40-236Z, run-2026-08-18T04-49-43-066Z, run-2026-08-18T05-07-03-585Z |
| L01 | rate-limits | r01-rate-limit-surface.ts | none published |
| L01b | rate-limits | r01-rate-limit-surface.ts | none published |
| L02 | rate-limits | l02-burst-shapes.ts | run-2026-10-13T05-09-36-511Z |
| M01b | usage-metering | m01-diy-usage-metering.ts | none published |
| M01c | usage-metering | m01-diy-usage-metering.ts | none published |
| M03 | usage-metering | m03-attribution-estimator.ts | none published |
| M04 | usage-metering | m04-gateway-exact-metering.ts | run-2026-08-18T06-31-21-134Z |
| M05 | usage-metering | m05-control-plane-store.ts | run-2026-08-18T06-21-24-941Z, run-2026-08-18T06-25-18-819Z |
| M06 | usage-metering | m06-idempotent-rollup.ts | run-2026-08-18T06-36-29-484Z, run-2026-08-18T06-39-38-374Z |
| M07 | usage-metering | m07-invoice-reconciliation.ts | none published |
Related
Section titled “Related”| If you are asking | Go to |
|---|---|
| Should tenants share an instance or get their own projects? | Tenant placement |
| What does each Management API operation cost in downtime? | Platform operation costs |
| The full platform build (provision, size, rate budget, OAuth) | Running a platform on the Management API |
References
Section titled “References”-
Supabase, “Your monthly invoice,” Supabase Docs. https://supabase.com/docs/guides/platform/your-monthly-invoice (read 2026-11-13; the “Discounted line items” and “Example invoice” sections). ↩
-
Supabase, “Supabase for Platforms,” Supabase Docs. https://supabase.com/docs/guides/integrations/supabase-for-platforms (read 2026-11-12). ↩
-
Supabase, “Management API introduction” (rate limits), Supabase Docs. https://supabase.com/docs/reference/api/introduction (read 2026-11-13). ↩ ↩2
-
Supabase, “Supabase API (v1),” OpenAPI document. https://api.supabase.com/api/v1-json (read 2026-11-13). ↩ ↩2 ↩3 ↩4 ↩5 ↩6
-
Supabase, “Access Control,” Supabase Docs. https://supabase.com/docs/guides/platform/access-control ↩
-
Supabase, “Supabase API (v2),” OpenAPI document. https://api.supabase.com/api/v2-json (read 2026-11-13). ↩ ↩2
-
Supabase, “Platform Audit Logs,” Supabase Docs. https://supabase.com/docs/guides/security/platform-audit-logs (read 2026-11-13). ↩
-
Supabase, “packages/api-types/types/platform.d.ts” (
AuditLogsResponse_Output), supabase/supabase, commit 6143441. https://raw.githubusercontent.com/supabase/supabase/614344149399/packages/api-types/types/platform.d.ts ↩ -
supabase-lab - the measurement harness;
experiments/usage-metering/carries M01-M07 with runbooks. ↩ -
Supabase, “Personal Access Tokens,” Supabase Docs. https://supabase.com/docs/guides/platform/personal-access-tokens (read 2026-10-07). ↩
-
Supabase, “Control your costs,” Supabase Docs. https://supabase.com/docs/guides/platform/cost-control (read 2026-11-13). ↩