Analytics

# Analytics

See how your brand is performing across social media, revenue, and website traffic -- all in one place.

## When to Use
- User wants to check social media follower growth or post engagement
- User needs a revenue overview or wants to review recent transactions
- User wants to see website traffic, top pages, or traffic sources
- User is evaluating campaign performance across channels
- User wants data to inform content strategy decisions

## How It Connects
- **Social Media** → Check post-level engagement metrics after publishing social content.
- **SEO** → Correlate traffic analytics with keyword ranking changes.
- **AI Visibility** → Compare traditional web traffic with AI platform visibility trends.
- **Blog** → Analyze traffic to blog articles to inform future content topics.
- **Newsletter** → Track how newsletter sends impact website traffic.

## Quick Start

Take a snapshot of your social media metrics:
```bash
clawpow analytics social snapshot --json
```

## Commands

### Social Snapshot
```bash
clawpow analytics social snapshot --json
clawpow analytics social snapshot --days 7 --json
clawpow analytics social snapshot --platform x --json
```
Fetch follower counts and engagement metrics from all connected social platform accounts. This is a read-only query that returns data directly.

**Options:**
- `--platform <platform>` -- Filter by a single platform: x, linkedin, threads, instagram
- `--days <number>` -- Time range in days (default: 30)

**Returns:** `{"aggregate": {"totalFollowers": number, "totalImpressions": number}, "accounts": [...]}`

### Social Post Metrics
```bash
clawpow analytics social posts --json
clawpow analytics social posts <platformPostId> --json
clawpow analytics social posts --platform x --days 7 --json
```
Fetch per-post engagement metrics for published posts. This is a read-only query that returns data directly.

**Options:**
- `<platformPostId>` (positional) -- Platform post ID for detail view (shows snapshot history)
- `--platform <list>` -- Comma-separated: x,linkedin,threads
- `--days <number>` -- Time range in days (default: 30)

**Returns (list):** `{"topPosts": [...], "recentPosts": [...]}` — each entry has `{"content": "...", "platform": "...", "publishedAt": number, "metrics": {"engagementRate": number, "impressions": number, "likes": number}}`

- `topPosts`: Top 10 posts sorted by engagement rate (highest first)
- `recentPosts`: Top 10 posts sorted by publish date (newest first)

**Returns (detail):** `{"content": "...", "publishedAt": number, "snapshots": [{"platform": "...", "snapshotAt": number, "metrics": {...}}]}`

Metrics vary by platform:
- **X:** likeCount, retweetCount, replyCount, impressionCount, quoteCount
- **LinkedIn:** likeCount, commentCount, shareCount, impressionCount
- **Threads:** likeCount, replyCount, repostCount, quoteCount, viewCount
- **Instagram:** account-level metrics (follower counts)

### Revenue Snapshot
```bash
clawpow analytics revenue snapshot --json
clawpow analytics revenue snapshot --days 7 --json
```
Fetch MRR, subscriber counts, and net revenue from connected Stripe account. This is a queued operation that runs asynchronously.

**Options:**
- `--days <number>` -- Time range in days (default: 30)

**Returns:** `{"runId": "...", "status": "queued"}`

Snapshot includes: MRR, active subscribers, net revenue, new subscribers, churned subscribers.

### Revenue Transactions
```bash
clawpow analytics revenue transactions --json
clawpow analytics revenue transactions --days 30 --json
```
Fetch recent charges and transactions from connected Stripe account. This is a queued operation that runs asynchronously.

**Options:**
- `--days <number>` -- Number of days of transaction history to fetch (default: 7)

**Returns:** `{"runId": "...", "status": "queued"}`

### Traffic Snapshot
```bash
clawpow analytics traffic snapshot --json
clawpow analytics traffic snapshot --days 7 --json
```
Fetch traffic snapshot including sessions, users, pageviews, bounce rate, and average session duration. This is a read-only query that returns data directly.

**Options:**
- `--days <number>` -- Time range in days (default: 30)

**Returns:** `{"current": {"sessions": number, "users": number, "pageviews": number, "bounceRate": number, "avgSessionDuration": number, "periodDays": number}, "deltas": {"sessions": number, "users": number, "pageviews": number, "bounceRate": number, "avgSessionDuration": number} | null}`

Deltas show the change compared to the previous equivalent period. Deltas are `null` when there is not enough historical data for comparison.

### Traffic Pages
```bash
clawpow analytics traffic pages --json
clawpow analytics traffic pages --days 7 --limit 10 --json
```
Fetch top pages by pageviews with traffic, bounce rate, and time on page. This is a read-only query that returns data directly.

**Options:**
- `--days <number>` -- Time range in days (default: 30)
- `--limit <number>` -- Maximum number of pages to return (default: 20)

**Returns:** `{"pages": [{"pagePath": "...", "pageTitle": "...", "pageviews": number, "users": number, "avgSessionDuration": number, "bounceRate": number, "snapshotAt": number}]}`

### Traffic Sources
```bash
clawpow analytics traffic sources --json
clawpow analytics traffic sources --days 7 --limit 10 --json
```
Fetch top traffic sources by sessions with source/medium, users, and bounce rate. This is a read-only query that returns data directly.

**Options:**
- `--days <number>` -- Time range in days (default: 30)
- `--limit <number>` -- Maximum number of sources to return (default: 20)

**Returns:** `{"sources": [{"source": "...", "medium": "...", "sessions": number, "users": number, "bounceRate": number, "snapshotAt": number}]}`

## Output Format

All commands support `--json` for structured output. Without `--json`, output is human-readable.

Read-only commands (social, traffic) return data directly. Queued operations (revenue) return a run ID immediately.

## Important Notes

- Always use `--json` for machine-parseable output
- Social snapshot and post metrics are read-only queries (return data directly, no credits consumed)
- Traffic snapshot, pages, and sources are read-only queries (return data directly, no credits consumed)
- Revenue snapshot and transactions are queued operations (consume credits)
- Social commands require connected social media accounts
- Revenue commands require a connected Stripe account
- Traffic commands require a connected Google Analytics property