Documentation
Everything you need to set up and use MetricOwl.
1. Create your account
Sign up at metricowl.ai/signup with your email. No credit card required for the free tier.
2. Connect your data source
During onboarding, paste your Google Sheet URL containing your measurement plan. MetricOwl will auto-detect your metric columns, owners, and targets. Alternatively, add metrics manually.
3. Assign metric owners
Each metric needs an owner — the person who will be nudged when it changes significantly. Enter their Slack handle (e.g., @jake). Optionally assign a guardian for data quality alerts.
4. Set your schedule
Configure when MetricOwl should scan metrics (e.g., Monday 7am), send reminders (e.g., Monday 2pm), and deliver the brief (e.g., Tuesday 9am). All times are timezone-aware.
5. Connect Slack
Click "Connect Slack" to install the MetricOwl bot in your workspace. Select the channel where you want briefs posted (e.g., #weekly-review). The bot needs permissions to send DMs and post to channels.
6. Run your first scan
Use the "Trigger Scan" button in the dashboard to run your first scan immediately. MetricOwl will read your metrics, detect any changes, and DM owners who have flagged metrics. Once owners respond, trigger the brief to see the compiled output.
Data sources
Each metric can pull its value from one of three sources: a Google Sheet cell (specify the sheet name and cell reference), a dashboard URL (MetricOwl takes a screenshot and extracts the value via AI), or manual entry (you update the value in the dashboard).
Change detection
MetricOwl compares the current value to last week's value. If the change exceeds your configured threshold (default 5%), the metric is flagged. It also detects movement away from target — if a metric was at 80% last week and the target is 90%, moving to 75% is flagged even if the percentage change is small.
Owners vs. Guardians
The owner is the business person responsible for a metric. They get nudged when the metric changes significantly. The guardian is the data person who ensures data quality — they get alerted on null values, stale data (same value 3+ weeks), or extreme swings (>50%).
Google Sheets
MetricOwl uses a service account to read your Google Sheet. Share the sheet with the service account email (provided during setup). We use read-only access — MetricOwl never writes to your sheet.
Dashboard URLs
For dashboards without API access, MetricOwl can take a screenshot and extract metric values using AI vision. The dashboard must be publicly accessible (no login required). We use Playwright for screenshots and Claude Vision for extraction.
Slack
MetricOwl installs as a Slack app in your workspace. It needs permissions to: send DMs to metric owners, post messages to your review channel, and respond to button interactions. All messages are sent as the MetricOwl bot — never as individual users.
API overview
The MetricOwl API is available on the Organization plan. It provides REST endpoints for managing metrics, triggering scans, and retrieving WBR data programmatically.
Authentication
API requests are authenticated with a Bearer token. Generate your API key in Settings > API. Include it in the Authorization header: Authorization: Bearer your-api-key.
Endpoints
GET /api/metrics — List all metrics and their current values. POST /api/scan — Trigger a metric scan. GET /api/wbrs — List all weekly reviews. GET /api/wbrs/:id — Get a specific weekly review with metrics, changes, and responses.
What permissions does MetricOwl need?
For Google Sheets: read-only access to the specific sheet (shared via service account email). For Slack: permission to send DMs, post to channels, and handle button interactions. For dashboard URLs: the dashboard must be publicly accessible — MetricOwl cannot log into password-protected dashboards.
How does dashboard scraping work?
MetricOwl uses Playwright (headless browser) to take a screenshot of your dashboard URL, then sends it to Claude Vision (Anthropic's AI) to extract the metric value. Screenshots are processed in memory and not stored. This works with any web-based dashboard that doesn't require authentication.
What data does MetricOwl store?
Only metric snapshots (name, value, date), owner responses to nudges, and workspace configuration. We never store raw data from your data sources, dashboard screenshots, or any data beyond what's needed for the WBR process.
Can I self-host MetricOwl?
Self-hosted deployment is available on the Organization plan. MetricOwl runs as a single Docker container with a PostgreSQL database. Contact us for setup instructions.
What happens if a data source is unavailable?
If MetricOwl can't read a metric (sheet unavailable, dashboard down, etc.), it marks that metric as "stale" in the brief and alerts the guardian if one is configured. The rest of the WBR continues normally.
Need help?
Reach us at support@metricowl.ai — we typically respond within a few hours.