---
title: "Platform-wide growth KPIs (platform admin only; aggregates only)"
method: GET
path: "/v1/admin/growth-metrics"
tags: ["admin"]
---

# Platform-wide growth KPIs (platform admin only; aggregates only)

`GET /v1/admin/growth-metrics`

## Request

- Base URL: `https://postbag.dev`
- URL: `https://postbag.dev/v1/admin/growth-metrics`
- Auth: HTTP bearer

Platform-admin only: allowed when the caller's email (the session user's email, or — for an API key — the owner member's email of the key's organization) is in the server's PLATFORM_ADMIN_EMAILS env var (comma-separated, empty by default). Any other caller gets 404 not_found, not 403, so a self-hosted operator who never sets PLATFORM_ADMIN_EMAILS never sees this endpoint exist. Returns COUNT aggregates across every organization — never emails, names, submission payloads, API keys, or per-organization dumps. Requires the read scope. This is the narrow platform aggregate exception defined by ADR-011. Every value is a current snapshot of retained database rows, so retention and user deletion can reduce totals and window counts; this is not an append-only historical funnel. Sandbox fields are explicitly prefixed `retained_` because housekeeping deletes every sandbox after expires_at, including claimed rows. `orgs_with_real_delivery_30d` is organizations with at least one successful (status=sent) Delivery of a non-test Submission in 30 days.

## Response `200`

ok

- GrowthMetrics
  - `generated_at` string, required: ISO-8601 instant the windows (7d / 30d) are computed from. Every metric is a snapshot of rows retained in the primary database at this instant, not an append-only historical total. Aggregates only — no emails, names, payloads, or keys.
  - `organizations` object, required
    - `total` integer, required
    - `created_7d` integer, required
    - `created_30d` integer, required
    - `by_plan` object, required: Counts from organization_settings.plan. Always includes free, pro, team and selfhost (0 when none). An organization without a settings row is counted as free.
      - `free` integer, required
      - `pro` integer, required
      - `team` integer, required
      - `selfhost` integer, required
  - `forms` object, required
    - `total` integer, required
    - `created_7d` integer, required
    - `created_30d` integer, required
    - `active` integer, required: Forms with at least one non-test Submission in the last 30 days.
  - `submissions` object, required
    - `total` integer, required
    - `last_7d` integer, required
    - `last_30d` integer, required
    - `real_last_30d` integer, required: Submissions with test=false received in the last 30 days.
    - `test_last_30d` integer, required: Submissions with test=true received in the last 30 days.
    - `orgs_with_real_delivery_30d` integer, required: Distinct organizations with at least one Delivery status=sent of a non-test Submission whose sent_at is in the last 30 days.
  - `sandboxes` object, required: Current retained anonymous sandbox staging rows (ADR-008), not a historical creation/claim/conversion funnel. Housekeeping deletes every sandbox after expires_at, including claimed rows.
    - `retained_created_30d` integer, required: Retained anonymous_sandboxes rows inserted in the last 30 days.
    - `retained_claimed_30d` integer, required: Retained sandbox rows whose claimed_at is in the last 30 days.
    - `retained_expired_or_blocked_30d` integer, required: Retained rows currently status expired or blocked whose created_at or expires_at falls in the last 30 days.
  - `destinations` object, required
    - `by_type` object, required: Destination counts keyed by type. Always includes email, telegram, webhook, slack and discord (0 when none); any other stored type is included as well.

## Other responses

- `400`: Error
- `401`: Error
- `403`: Error
- `404`: Not found
- `409`: Error
- `422`: Error

---

[API](https://skmtc.dev/postbag/apis/postbag-api.md) · [All operations](https://skmtc.dev/postbag/apis/postbag-api/llms.txt) · [OpenAPI document](https://skmtc.dev/postbag/apis/postbag-api/revisions/3da976524695?raw)