Skip to content

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.

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/addons returns 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 with 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, so compute-hours are provisioned wall time on both. On a Free org the data API answers HTTP 540 Project paused immediately after a manual pause, and two auto-paused free-plan projects had no DNS record for their hostname (read 2026-09-23). Read status on every sweep and count hours only while the project is not INACTIVE. 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’s status does 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() over POST /v1/projects/{ref}/database/query. The deltas compress: a repeat()-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=15min returned 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.

  1. A tenant/owner -> project_ref map in your control-plane database, written at provision time.
  2. 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.
  3. 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.

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/projects returns the new project, ref included, in its 201 body,4 so the service that creates a project records ref -> unit from 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 new name,4 so a unit prefix in the name can drift from the map.
  • The sweep reads the organization listing. GET /v1/organizations/{slug}/projects pages with limit (at most 100) and offset and reports pagination.count.4 Diffing it against the map puts any project created outside the write path into an unattributed bucket 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}/branches and GET /v1/projects/{ref}/branches/{name} (parent_project_ref beside the branch’s project_ref); GET /v1/branches/{branch_id_or_ref} describes connection details with no parent field, and the organization listing marks a row with is_branch but 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}/roles assigns an org-wide role, or a project-scoped one when projects is given, and its OpenAPI entry carries x-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 declares token_type, token_hash, token_alias (the token’s name as shown in the dashboard) and oauth_app_id / oauth_app_name for each actor.8 A PAT is refused on that route with 401 JWT could not be decoded while the same PAT answers 200 on /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 an unattributed ref 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.

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:

ModuleWhat it provesMeasured
M03The estimator, read-only against a live org: enumerate -> SKU -> cost table3 projects at $9.81/mo each, $29.43 org monthly compute - matching the invoice’s own rate card
M04Per-key metering at a credential-proxy gateway is exact: one scoped key per tenant = a per-tenant usage ledger7 proxied calls -> exactly 7 events, 5 -> 5, correct project ref and status on every event
M05One project can hold the tenant map + rollups including itself (self-inclusion), and per-tenant attribution inside a shared schema is exact from SQL4/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
M06The rollup is idempotent under re-flush and late eventsRe-flush identical; a late event into a closed window moves its total by exactly its quantity; duplicate idempotency keys rejected; other windows untouched
M07The invoice parses into a dataset and reconciles against the live org91 per-ref lines, 32 refs, 3 matched by name, 29 deleted since invoice; standing projects billed 592/600 h (98.7% of the window)

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.

PracticeEvidenceModule
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 userThe 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

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/addons returns the selected compute SKU; multiply by the invoice’s own rates for that SKU’s hours.
  • Database size: pg_database_size() over POST /v1/projects/{ref}/database/query. To confirm the deltas are real, grow a table with random bytes, not repeat()-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=15min should return exactly the requests you sent, visible after 61 s.
  • Pace the sweep by x-ratelimit-remaining on 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.

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.

  • 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.
ClaimHow it was checked
Invoice itemises usage lines per project ref; plan/MAU/functions/realtime/discounts do not itemiseRead off a Pro-plan invoice, 2026-08
Compute SKU per project via billing/addons; pause refused on ProMeasured 2026-08-17/18 - 400 Project is not free-tier
Micro rate $0.01344/hrRead off the invoice’s compute line
pg_database_size + Storage listing exactMeasured 2026-08-17 - byte-exact storage; TOAST compression caveat on database size
usage.api-counts exact (13/13) at 61 s lagMeasured 2026-08-17/18, reproduced after accounting fix
No per-service egress bytes in the per-project APIMetrics endpoint enumerated 2026-08-18 - node_/pg_/pgbouncer_ families only
Scoped-key gateway metering: 200/278 families, 403 deny-by-default, ~1 s auditMeasured 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/minMeasured 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 100Documented in the public v1 spec (read 2026-11-13); not measured
No creator/tag/label/metadata field on the project; names mutableDocumented 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 EnterpriseDocumented 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’ projectsDocumented for the dashboard (Access Control guide); not measured on the Management API
A PAT cannot read the organization audit logMeasured 2026-10-02 on a Team org: 401 on the dashboard route, 200 on /v1 (BA06)

No repo files are edited: this guide defines a control plane you build. The artefacts it asks for:

ArtefactWhat it is
The tenant maptenant/owner -> project_ref, written at provision time; module M05 keeps it in a project’s own schema
The hourly usage rowsCompute SKU, status, database size, storage bytes and request-count deltas per project, one row per project per hour
The monthly joinThat usage table joined against the invoice’s per-ref lines
The scoped-key gatewayOne key per tenant, metering every proxied call (M04)
experiments/usage-metering/The tested reference implementation in supabase-lab, M03-M07
If you are askingGo 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
  1. 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). ↩

  2. Supabase, “Supabase for Platforms,” Supabase Docs. https://supabase.com/docs/guides/integrations/supabase-for-platforms (read 2026-11-12). ↩

  3. Supabase, “Management API introduction” (rate limits), Supabase Docs. https://supabase.com/docs/reference/api/introduction (read 2026-11-13). ↩ ↩2

  4. Supabase, “Supabase API (v1),” OpenAPI document. https://api.supabase.com/api/v1-json (read 2026-11-13). ↩ ↩2 ↩3 ↩4 ↩5 ↩6

  5. Supabase, “Access Control,” Supabase Docs. https://supabase.com/docs/guides/platform/access-control ↩

  6. Supabase, “Supabase API (v2),” OpenAPI document. https://api.supabase.com/api/v2-json (read 2026-11-13). ↩ ↩2

  7. Supabase, “Platform Audit Logs,” Supabase Docs. https://supabase.com/docs/guides/security/platform-audit-logs (read 2026-11-13). ↩

  8. 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 ↩

  9. supabase-lab - the measurement harness; experiments/usage-metering/ carries M01-M07 with runbooks. ↩

  10. Supabase, “Personal Access Tokens,” Supabase Docs. https://supabase.com/docs/guides/platform/personal-access-tokens (read 2026-10-07). ↩

  11. Supabase, “Control your costs,” Supabase Docs. https://supabase.com/docs/guides/platform/cost-control (read 2026-11-13). ↩