Projects & Apps

Owlmetry uses a two-level hierarchy to organize your tracking: projects group related apps by product, and apps represent individual platform-specific builds.

Projects

A project represents a product or service. If you ship a mobile app called "Acme" on iOS and Android with a web dashboard, all three would live under a single "Acme" project.

Projects are team-scoped and identified by a unique slug. They provide a shared namespace for:

• Metric definitions -- performance tracking is defined per-project
• Funnel definitions -- conversion funnels span apps within a project
• Integrations -- third-party services like RevenueCat
• Issue alerting -- per-project issue_alert_frequency (none, hourly, 6_hourly, daily (default), weekly) controls the digest cadence only; instant issue.new push fan-out fires every scan regardless
• Attachment quotas -- per-user and project-wide byte ceilings
• Apps -- the platform-specific builds that send events

Each project also has a required #RRGGBB hex color used throughout the dashboard to distinguish projects at a glance. If you omit the color on creation, the server auto-picks one from a 20-entry palette, avoiding colors already in use by other non-deleted projects in the same team. You can change the color any time via PATCH /v1/projects/:id, owlmetry project update --color, or the MCP update-project tool.

Projects are managed through the dashboard, the CLI, or the API.

Data Retention

Each project has configurable data retention policies that control how long event data is kept:

A daily background job deletes events older than the retention period. Set retention per-project via the dashboard, CLI (--retention-events, --retention-metrics, --retention-funnels), or API. Set a value to null to use the system default.

Retention values must be between 1 and 3,650 days (approximately 10 years). Metric and funnel definitions are not affected by retention -- only the underlying event data is deleted.

Apps

An app represents a single platform-specific build within a project. Each app has a platform, an optional bundle ID, and its own client API key for event ingestion.

Platforms

Every app has a broad platform that categorizes what kind of build it is:

Environments

While an app has a single platform, the events it sends carry a more specific environment field that records the exact runtime:

This distinction allows a single "apple" platform app to receive events from iOS, iPadOS, and macOS environments, which the SDKs detect automatically.

Platform-to-Environment Mapping

Each platform allows a specific set of environments:

Bundle ID

Apps with a platform other than backend require a bundle_id (e.g., com.example.myapp). The ingest endpoint validates that the bundle_id in each request matches the app's registered bundle ID on every ingestion request.

Backend-platform apps have no bundle ID, and the ingest route skips this validation for them.

Bundle IDs are immutable after creation. The update endpoint only accepts a name change. If you need to change a bundle ID, delete the app and create a new one.

Auto-Created Client Key

When you create an app, Owlmetry automatically generates a client API key (owl_client_ prefix) as a row in the api_keys table, scoped to that app. The key is returned in the app creation response so you can configure your SDK immediately, and remains viewable at any time from the API Keys page in the dashboard.

Latest App Version

Each app response includes three fields tracking the current public release: latest_app_version, latest_app_version_updated_at, and latest_app_version_source ("app_store" for Apple apps resolved via iTunes Lookup, "computed" for Android/Web/Backend computed from production events). These power the green/amber version badges shown in events, users, and issues across the dashboard, CLI, and MCP. See Latest Version Detection for how it's resolved and refreshed.

Typical Setup

A common configuration for a cross-platform mobile product:

All four apps share the same project, so metric definitions, funnel definitions, and cross-platform analytics are unified under "Acme."

For managing projects and apps, see the CLI projects guide, the CLI apps guide, or the API reference.