SubmetryDocumentationSet up your app →

Agent API

Read analytics with a scoped sub_ro_ key from API & MCP. Choose all apps or a selection; save the secret shown once. It cannot ingest events or change apps, providers, team access or settings. MCP publishes the same analytics through https://api.submetry.com/v1/mcp.

Private sub_sk_ server keys remain app-scoped administrative credentials. Public sub_pk_ ingestion keys cannot read metrics. Dashboard browsers use HttpOnly sessions; accepted team viewers only read their shared apps.

curl "https://api.submetry.com/v1/portfolio?days=30&environment=production" \
  -H "Authorization: Bearer $SUBMETRY_READ_ONLY_KEY"

Read endpoints

Path (GET)Result
/v1/appsAccessible app metadata
/v1/portfolioAggregate totals and app comparison; explicit partial errors
/v1/apps/APP_ID/dashboardOverview, previous period, trend, onboarding, cohorts, acquisition and revenue
/v1/apps/APP_ID/advancedAdvanced analytics from raw history
/v1/apps/APP_ID/eventsEvent counts, unique users and properties
/v1/apps/APP_ID/events/EVENT_NAMENamed event details
/v1/apps/APP_ID/live?limit=100Descending sanitized raw events, maximum 500
/v1/apps/APP_ID/usersUp to 500 user summaries plus total/truncation metadata
/v1/apps/APP_ID/users/USER_IDIdentity-linked chronological journey, SDK time in seconds
/v1/apps/APP_ID/cohorts?granularity=weekDay/week/month matrices, partial periods and future nulls
/v1/apps/APP_ID/devicesDevice/OS/language/version/status groups, sessions and active users now
/v1/apps/APP_ID/funnelsOrdered funnel steps
/v1/apps/APP_ID/revenueObserved subscription lifecycle
/v1/apps/APP_ID/releasesPublication annotations
/v1/apps/APP_ID/releases/compare?left=1.0&right=1.1Two versions under the same filters

URL-encode names, versions and user IDs. Filters accept days 1–366, environment production/debug/sandbox/testflight/all, ISO from/to dates, country, app_version, source, paywall, product and platform. Dates use the persisted app IANA timezone unless overridden explicitly. Currency totals use USD; unavailable proceeds remain null rather than an invented net value.

Freshness and limits

Standard Cloudflare dashboards use ten-minute snapshots. Live events, users, devices, cohorts, releases comparisons and custom analytics read Iceberg; storage propagation can delay new rows. Interfaces poll every 10–15 seconds; polling does not accelerate the snapshot schedule.

Raw reads fail explicitly above 100,000 rows or 16 MiB encoded JSON; snapshots also enforce a D1 row-size bound. Partitioned aggregation is required for larger workloads. Journey and feed responses remove provider payloads and sensitive credential properties. Zero events and unknown financial metrics remain distinct.

Revenue requires a verified RevenueCat or Superwall webhook. OAuth import does not activate a webhook or backfill transactions.