# Analytics

> Analyze storefront page performance, conversions, and experiment results

Canonical URL: https://fa7e86e3d553:3005/tools/analytics

> **MCP v3 routing:** The operation names on this page are retained as action-contract references. Do not call them as top-level tools. Pass the former name to `lexsis_discover`, then call the returned router and action with the documented parameters inside `args`.

Tools for analyzing storefront page performance. Use these to understand
traffic, conversions, revenue, and experiment results before making
optimization decisions.

Open <AppLink to="analytics">Storefront Analytics</AppLink> for the merchant
dashboard.

---

## get_analytics_timeseries

Retrieve time series data for key metrics. Returns daily or weekly series for hits, conversions, revenue, AOV, or CTA clicks.

### Parameters

| Param | Type | Required | Description |
|-------|------|----------|-------------|
| `workspace_id` | string (UUID) | Yes | Workspace UUID |
| `metric` | `"hits"` \| `"conversions"` \| `"revenue"` \| `"aov"` \| `"cta_clicks"` | No | Metric to retrieve (default: `"conversions"`) |
| `period` | `"7d"` \| `"30d"` \| `"90d"` | No | Time period (default: `"30d"`) |
| `granularity` | `"day"` \| `"week"` | No | Data granularity (default: `"day"`) |
| `page_id` | string (UUID) | No | Filter to a specific page (omit for all pages) |

### Metric Definitions

- **`hits`** — Page views
- **`conversions`** — Checkout completions
- **`revenue`** — Total revenue in cents
- **`aov`** — Average order value
- **`cta_clicks`** — CTA button clicks

### Returns

Array of data points:
```typescript
Array<{
  date: string       // ISO date string (YYYY-MM-DD)
  value: number      // Metric value
  metric: string     // Metric name
}>
```

### Example

```json
{
  "name": "get_analytics_timeseries",
  "arguments": {
    "workspace_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "metric": "conversions",
    "period": "30d",
    "granularity": "day"
  }
}
```

**Response:**
```json
[
  { "date": "2026-05-27", "value": 42, "metric": "conversions" },
  { "date": "2026-05-28", "value": 38, "metric": "conversions" },
  { "date": "2026-05-29", "value": 51, "metric": "conversions" }
]
```

**Filter to specific page:**
```json
{
  "name": "get_analytics_timeseries",
  "arguments": {
    "workspace_id": "f47ac10b-...",
    "metric": "revenue",
    "period": "90d",
    "granularity": "week",
    "page_id": "a1b2c3d4-..."
  }
}
```

### When to Use

- **Spot trends** — is traffic growing or declining?
- **Measure A/B test impact** — compare before/after periods
- **Identify seasonality** — do conversions spike on weekends?
- **Pre-optimization baseline** — capture current performance before changes

---

## get_page_analytics

Deep-dive on a single page. Returns CVR, bounce rate, avg time on page, top traffic sources, device split, and top-converting sections.

### Parameters

| Param | Type | Required | Description |
|-------|------|----------|-------------|
| `page_id` | string (UUID) | Yes | Page UUID |
| `workspace_id` | string (UUID) | Yes | Workspace UUID |

### Returns

```typescript
{
  page_id: string
  cvr: number                        // Conversion rate (0-1)
  bounce_rate: number                // Bounce rate (0-1)
  avg_time_on_page: number           // Seconds
  top_sources: Array<{
    source: string                   // Traffic source (e.g. "google", "facebook")
    visitors: number
    cvr: number
  }>
  device_split: {
    mobile: number                   // % mobile traffic (0-1)
    desktop: number                  // % desktop traffic (0-1)
  }
  top_converting_sections: Array<{
    section_id: string               // Section ID from the page
    cta_clicks: number               // Number of CTA clicks in this section
    conversion_lift: number          // CVR lift attributed to this section (0-1)
  }>
}
```

### Example

```json
{
  "name": "get_page_analytics",
  "arguments": {
    "page_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "workspace_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
  }
}
```

**Response:**
```json
{
  "page_id": "a1b2c3d4-...",
  "cvr": 0.048,
  "bounce_rate": 0.32,
  "avg_time_on_page": 127,
  "top_sources": [
    { "source": "google", "visitors": 1842, "cvr": 0.051 },
    { "source": "facebook", "visitors": 1204, "cvr": 0.043 },
    { "source": "direct", "visitors": 892, "cvr": 0.052 }
  ],
  "device_split": {
    "mobile": 0.68,
    "desktop": 0.32
  },
  "top_converting_sections": [
    { "section_id": "hero", "cta_clicks": 512, "conversion_lift": 0.021 },
    { "section_id": "testimonials", "cta_clicks": 287, "conversion_lift": 0.014 },
    { "section_id": "final-cta", "cta_clicks": 891, "conversion_lift": 0.038 }
  ]
}
```

### When to Use

- **Before redesigning a page** — identify which sections perform best
- **Diagnose high bounce rate** — check `avg_time_on_page` and `top_sources`
- **Mobile optimization** — if `device_split.mobile > 0.6`, prioritize mobile layout
- **Section-level insights** — use `top_converting_sections` to decide what to A/B test

---

## Workflow Examples

### Pre-Optimization Audit

```typescript
// 1. Check overall trends
const timeseries = await get_analytics_timeseries({
  workspace_id: "...",
  metric: "conversions",
  period: "30d"
});

// 2. Deep-dive on a specific page
const pageAnalytics = await get_page_analytics({
  page_id: "...",
  workspace_id: "..."
});

// Decision: 
// - High bounce rate → redesign hero
// - Low CVR on mobile → optimize for mobile
// - Low checkout rate → review offer, cart, and purchase flow
```

### Post-Experiment Analysis

```typescript
// Compare pre/post periods
const before = await get_analytics_timeseries({
  workspace_id: "...",
  metric: "conversions",
  period: "30d",        // Before experiment
  page_id: "..."
});

// Run experiment, scale winner, wait 30 days

const after = await get_analytics_timeseries({
  workspace_id: "...",
  metric: "conversions",
  period: "30d",        // After scaling winner
  page_id: "..."
});

// Calculate lift
const beforeAvg = before.reduce((sum, d) => sum + d.value, 0) / before.length;
const afterAvg = after.reduce((sum, d) => sum + d.value, 0) / after.length;
const lift = (afterAvg - beforeAvg) / beforeAvg;
```

---

## Best Practices

1. **Check analytics before optimizing** — don't guess, measure
2. **Use `get_page_analytics` for diagnosis** — it pinpoints the problem (bounce, device, section)
3. **Compare time periods** — 7d for quick checks, 30d for trends, 90d for seasonality
4. **Section-level insights** — use `top_converting_sections` to focus A/B tests on high-impact areas
5. **Mobile-first if `device_split.mobile > 0.6`** — most traffic is mobile, optimize there first