AI Insights

​

What is the AI Assistant?

• Natural language processing: Ask questions in plain English
• Automated query generation: Converts questions to SQL and analytics queries
• Multi-step reasoning: Breaks down complex questions into sub-tasks
• Tool execution: Accesses analytics data, goals, funnels, links, and more
• Interactive visualizations: Generates charts, tables, and maps
• Proactive insights: Identifies trends, anomalies, and opportunities

​

How It Works

​

Agent Pipeline

1. Triage: Classifies your question type
2. Tool selection: Chooses appropriate analytics tools
3. Query execution: Fetches data from ClickHouse
4. Analysis: Interprets results and generates insights
5. Reflection: Validates answer quality
6. Response: Returns formatted answer with visualizations

​

Supported Models

• Primary: Claude 3.5 Sonnet (analytics agent)
• Reflection: GPT-4o-mini (quality validation)
• Triage: GPT-4o-mini (request classification)

​

Asking Questions

​

Via Chat Interface

1. Click the AI button in the dashboard
2. Type your question
3. Press Enter or click Send
4. View the AI’s response with data and charts

​

Via Keyboard Shortcut

• Press A anywhere in the dashboard
• Type your question
• Get instant insights

​

Question Types

​

Traffic Analysis

• “How many visitors did I have last week?”
• “What’s my traffic trend for the last 30 days?”
• “Show me pageviews by day for the last month”
• “Compare this week’s traffic to last week”

​

Page Performance

• “What are my top 10 pages?”
• “Which pages have the longest time on page?”
• “Show me entry pages ranked by visitors”
• “What pages have the highest bounce rate?”

​

Traffic Sources

• “Where is my traffic coming from?”
• “Show me top referrers this month”
• “What’s the breakdown of direct vs referral traffic?”
• “Which social platforms send the most visitors?”

​

Geographic Analysis

• “What countries are my visitors from?”
• “Show me a map of visitor locations”
• “Which regions have the most traffic?”
• “How many visitors from the US vs UK?”

​

Device & Browser

• “What percentage of visitors use mobile?”
• “Show me device type distribution”
• “Which browsers are most popular?”
• “What’s the desktop vs mobile split?”

​

Goals & Conversions

• “Show me all my goals”
• “What’s the conversion rate for newsletter signups?”
• “Create a goal for purchase completions”
• “How are my goals performing this month?”
• “Which goal has the highest conversion rate?”

​

Funnels

• “Show me my funnels”
• “What’s the conversion rate for the signup funnel?”
• “Which step in the checkout funnel has the biggest drop-off?”
• “Create a funnel for the onboarding flow”
• “How does the signup funnel perform by referrer?”

​

Custom Events

• “What custom events are being tracked?”
• “Show me the ‘button_click’ event frequency”
• “What properties does the ‘purchase’ event have?”
• “Show me recent ‘signup’ events”

​

Performance Metrics

• “What’s my average page load time?”
• “Show me TTFB for the homepage”
• “Which pages are the slowest?”
• “How are my Core Web Vitals?”

​

Short Links

• “Show me all my short links”
• “Create a link for the summer sale”
• “How many clicks did the ‘bf24’ link get?”
• “What’s the best performing link?”

​

Comparative Analysis

• “Compare this week to last week”
• “Show me month-over-month growth”
• “How does mobile traffic compare to desktop?”
• “Which performs better: organic or paid traffic?”

​

AI Tools

​

Query Builder

• traffic: Pageviews, visitors, sessions over time
• summary_metrics: High-level KPIs
• top_pages: Most viewed pages
• top_referrers: Traffic sources
• devices: Device type breakdown
• browsers: Browser distribution
• countries: Geographic distribution
• performance: Load times, TTFB, Web Vitals
• custom_events: Event tracking data

​

SQL Execution

SELECT 
  date,
  COUNT(*) as pageviews,
  COUNT(DISTINCT visitor_id) as visitors
FROM pageviews
WHERE client_id = {websiteId:String}
  AND date >= {startDate:Date}
GROUP BY date
ORDER BY date

​

Goals Tools

• list_goals: List all goals
• get_goal_by_id: Get goal details
• get_goal_analytics: Conversion metrics
• create_goal: Create new goal
• update_goal: Modify existing goal
• delete_goal: Remove goal

​

Funnels Tools

• list_funnels: List all funnels
• get_funnel_by_id: Get funnel details
• get_funnel_analytics: Conversion rates and drop-offs
• get_funnel_analytics_by_referrer: Referrer breakdown
• create_funnel: Create new funnel

​

Links Tools

• list_links: List all short links
• get_link: Get link details
• search_links: Search by name/slug/URL
• create_link: Create new link
• update_link: Modify link
• delete_link: Remove link

​

Annotations Tools

• list_annotations: Chart annotations
• create_annotation: Mark events on charts
• update_annotation: Edit annotations
• delete_annotation: Remove annotations

​

Visualizations

​

Chart Types

{"type":"line-chart","title":"Traffic Over Time","data":{"x":["2024-01-01","2024-01-02"],"pageviews":[100,150],"visitors":[80,120]}}

{"type":"bar-chart","title":"Top Pages","data":{"x":["/home","/about","/pricing"],"views":[1000,800,600]}}

{"type":"pie-chart","title":"Device Distribution","data":{"labels":["Desktop","Mobile","Tablet"],"values":[650,280,70]}}

{"type":"data-table","title":"Performance Metrics","columns":[{"key":"page","header":"Page"},{"key":"visitors","header":"Visitors","align":"right"}],"rows":[{"page":"/home","visitors":1500}]}

{"type":"mini-map","title":"Visitor Locations","countries":[{"name":"United States","country_code":"US","visitors":1200,"percentage":40}]}

{"type":"referrers-list","title":"Traffic Sources","referrers":[{"name":"Google","domain":"google.com","visitors":500,"percentage":45.5}]}

​

Data Integrity

​

Never Hallucinates

• NEVER invents metrics or numbers
• NEVER provides fake data
• ALWAYS calls tools before answering
• ONLY uses real data from tool results

​

Transparency

• Shows raw data from queries
• Explains data limitations
• Notes low sample sizes
• Flags data quality issues

​

Accuracy

• Uses exact labels from results
• Doesn’t rename or transform data
• Includes time context (“last 7 days”)
• Compares periods automatically

​

Advanced Features

​

Batch Queries

get_data({
  websiteId: 'site-123',
  queries: [
    { type: 'summary_metrics', preset: 'last_30d' },
    { type: 'top_pages', preset: 'last_30d' },
    { type: 'top_referrers', preset: 'last_30d' }
  ]
})

​

Multi-Step Reasoning

1. Get top pages from Google (filter: referrer = google.com)
2. List all goals
3. Calculate conversion rate for each page
4. Rank by conversion rate
5. Present top 10 with chart

​

Proactive Insights

• “Traffic dropped 25% because organic search declined”
• “Mobile conversion is 40% lower than desktop - consider mobile UX improvements”
• “Page load time increased 2x last week - investigate performance”

​

Contextual Recommendations

• “Only 3 days of data available - results may not be representative”
• “Low sample size (less than 100 events) - avoid strong conclusions”
• “Unusual spike detected on Jan 15 - consider adding annotation”

​

Confirmation Flows

​

Creating Goals

1. AI calls create_goal with confirmed: false
2. Shows preview of goal configuration
3. Asks: “Do you want to create this goal?”
4. User confirms: “Yes, create it”
5. AI calls create_goal with confirmed: true
6. Goal created

​

Creating Funnels

1. Preview with confirmed: false
2. Show funnel steps
3. Request confirmation
4. Create with confirmed: true

​

Deleting Resources

1. AI calls delete_* with confirmed: false
2. Shows what will be deleted
3. Warns about data loss
4. User confirms
5. AI deletes with confirmed: true

​

Date Handling

• “last week” → Mon-Sun of previous week
• “last 7 days” → Exactly 7 days ago to now
• “this month” → First day to today
• “yesterday” → Previous day
• “last 30 days” → 30 days ago to now

​

Privacy & Security

• User-scoped: Only sees your website’s data
• No training: Your data is not used to train models
• No sharing: Conversations are private
• Encrypted: All data in transit is encrypted
• GDPR compliant: No personal data exposed

​

Limitations

​

Bounce Rate

• Only available at site level
• Cannot calculate per-page bounce rate
• AI clarifies this limitation when asked

​

Historic Data

• Limited to data retention period (typically 90 days - 2 years)
• Cannot analyze data before tracking was installed

​

Real-Time

• Data has less than 1 minute latency from ingestion
• Not truly real-time, but near real-time

​

Custom SQL

• Must use SELECT/WITH statements only
• No INSERT/UPDATE/DELETE
• Must use parameter placeholders for safety

​

Best Practices

​

Be Specific

​

Provide Context

​

Ask Follow-Ups

1. “Show me top pages”
2. “Now filter to just mobile traffic”
3. “What’s the average time on page?”

​

Request Visualizations

​

Verify Important Decisions

• Review preview configurations
• Check dates and filters
• Confirm metrics are correct

​

Troubleshooting

​

AI Says “No Data”

• Check your date range
• Verify tracking is installed
• Ensure events are being sent
• Try a broader time period

​

AI Doesn’t Understand

• Use simpler language
• Break into smaller questions
• Provide more context

​

Charts Not Showing

• Disable ad blockers
• Clear cache
• Try different browser

​

Slow Responses

• Large date ranges
• Multiple aggregations
• Custom SQL queries

​

Next Steps