# Agent API

Read analytics with a scoped `sub_ro_` key from [API & MCP](https://submetry.com/app/agents). Choose all apps or a selection; save the secret shown once. It cannot ingest events or change apps, providers, team access or settings. [MCP](https://submetry.com/docs/mcp.md) 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.

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

## Read endpoints

| Path (GET) | Result |
| --- | --- |
| `/v1/apps` | Accessible app metadata |
| `/v1/portfolio` | Aggregate totals and app comparison; explicit partial errors |
| `/v1/apps/APP_ID/dashboard` | Overview, previous period, trend, onboarding, cohorts, acquisition and revenue |
| `/v1/apps/APP_ID/advanced` | Advanced analytics from raw history |
| `/v1/apps/APP_ID/events` | Event counts, unique users and properties |
| `/v1/apps/APP_ID/events/EVENT_NAME` | Named event details |
| `/v1/apps/APP_ID/live?limit=100` | Descending sanitized raw events, maximum 500 |
| `/v1/apps/APP_ID/users` | Up to 500 user summaries plus total/truncation metadata |
| `/v1/apps/APP_ID/users/USER_ID` | Identity-linked chronological journey, SDK time in seconds |
| `/v1/apps/APP_ID/cohorts?granularity=week` | Day/week/month matrices, partial periods and future nulls |
| `/v1/apps/APP_ID/devices` | Device/OS/language/version/status groups, sessions and active users now |
| `/v1/apps/APP_ID/funnels` | Ordered funnel steps |
| `/v1/apps/APP_ID/revenue` | Observed subscription lifecycle |
| `/v1/apps/APP_ID/releases` | Publication annotations |
| `/v1/apps/APP_ID/releases/compare?left=1.0&right=1.1` | Two 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](https://submetry.com/docs/revenuecat.md) or [Superwall](https://submetry.com/docs/superwall.md) webhook. OAuth import does not activate a webhook or backfill transactions.
