Agent Playbook

Simbioza Website Analytics Integration Guide

This playbook explains how AI agents can push website analytics data to the Simbioza Analytics dashboard via REST endpoints.

📋 Table of Contents

1. Overview

The Simbioza Website Analytics dashboard is a real-time analytics page displaying key website performance metrics, traffic insights, and AI-generated recommendations for the Simbioza website.

What it displays:

Live KPIs (active visitors, sessions, pageviews, bounce rate, conversions)
Traffic overview charts (7d/30d/90d comparisons)
Top pages performance table
Traffic source breakdown (organic, direct, referral, social, etc.)
AI-powered insights and prioritized recommendations
Alerts and anomaly detection

When to push data:

After analyzing website analytics data from Google Analytics, Plausible, or similar tools
When you detect significant traffic changes or anomalies
After generating new AI insights or recommendations
On a scheduled basis (e.g., every hour, every 6 hours, daily)

💡 Key Concept: All data is pushed by agents via POST endpoints. The dashboard polls /api/simbioza-analytics/all every 30 seconds to display the latest data.

2. Authentication

Current status: The API endpoints do not require a Bearer token or API key. This matches the existing project pattern for internal endpoints.

⚠️ Future Authentication

If Bearer token authentication is added in the future, you will need to include anAuthorization: Bearer TOKEN header in all POST requests. Check the endpoint implementation in app/api/simbioza-analytics/*/route.ts for updates.

Current request format:

curl -X POST https://dashboard.thesherminator.com/api/simbioza-analytics/live-kpis \
  -H "Content-Type: application/json" \
  -d '{...}'

3. Full API Reference

GET /api/simbioza-analytics/all

Fetches all current analytics data in one response.

Example Request:

curl https://dashboard.thesherminator.com/api/simbioza-analytics/all

Example Response:

{
  "liveKpis": { ... },
  "trafficChart": { ... },
  "topPages": { ... },
  "trafficSources": { ... },
  "aiInsights": { ... },
  "alerts": { ... }
}

💡 Each section will be null if no data has been pushed yet.

POST /api/simbioza-analytics/live-kpis

Updates live KPI metrics.

Body Schema:

{
  "activeVisitors": number,        // Current active visitors
  "todaySessions": number,         // Total sessions today
  "todayPageviews": number,        // Total pageviews today
  "avgSessionDuration": string,    // Format: "Xm Ys" (e.g., "3m 42s")
  "bounceRate": number,            // Percentage 0-100 (e.g., 42.5)
  "goalConversions": number,       // Total conversions today
  "updatedAt": string,             // ISO 8601 timestamp
  "trends": {                      // Optional: vs yesterday
    "activeVisitors": number,      // Percent change (e.g., 12 for +12%)
    "todaySessions": number,
    "todayPageviews": number,
    "avgSessionDuration": number,
    "bounceRate": number,
    "goalConversions": number
  }
}

Example Request:

curl -X POST https://dashboard.thesherminator.com/api/simbioza-analytics/live-kpis \
  -H "Content-Type: application/json" \
  -d '{
    "activeVisitors": 47,
    "todaySessions": 1234,
    "todayPageviews": 5678,
    "avgSessionDuration": "3m 42s",
    "bounceRate": 42.5,
    "goalConversions": 89,
    "updatedAt": "2026-04-05T12:00:00Z",
    "trends": {
      "activeVisitors": 12,
      "todaySessions": 8,
      "todayPageviews": 15,
      "avgSessionDuration": -5,
      "bounceRate": -3,
      "goalConversions": 22
    }
  }'

Example Success Response:

{ "success": true }

POST /api/simbioza-analytics/traffic-chart

Updates traffic overview chart data.

Body Schema:

{
  "period": "7d" | "30d" | "90d",
  "current": [
    { "date": string, "sessions": number }
  ],
  "previous": [
    { "date": string, "sessions": number }
  ]
}

Example Request:

curl -X POST https://dashboard.thesherminator.com/api/simbioza-analytics/traffic-chart \
  -H "Content-Type: application/json" \
  -d '{
    "period": "7d",
    "current": [
      { "date": "Mon", "sessions": 850 },
      { "date": "Tue", "sessions": 920 },
      { "date": "Wed", "sessions": 1050 },
      { "date": "Thu", "sessions": 980 },
      { "date": "Fri", "sessions": 1200 },
      { "date": "Sat", "sessions": 780 },
      { "date": "Sun", "sessions": 650 }
    ],
    "previous": [
      { "date": "Mon", "sessions": 780 },
      { "date": "Tue", "sessions": 820 },
      { "date": "Wed", "sessions": 900 },
      { "date": "Thu", "sessions": 850 },
      { "date": "Fri", "sessions": 1050 },
      { "date": "Sat", "sessions": 680 },
      { "date": "Sun", "sessions": 580 }
    ]
  }'

Example Success Response:

{ "success": true }

POST /api/simbioza-analytics/top-pages

Updates top pages performance data.

Body Schema:

{
  "pages": [
    {
      "url": string,
      "pageviews": number,
      "uniqueVisitors": number,
      "avgTimeOnPage": string,   // Format: "Xm Ys"
      "bounceRate": number        // Percentage 0-100
    }
  ],
  "updatedAt": string             // ISO 8601 timestamp
}

Example Request:

curl -X POST https://dashboard.thesherminator.com/api/simbioza-analytics/top-pages \
  -H "Content-Type: application/json" \
  -d '{
    "pages": [
      {
        "url": "/",
        "pageviews": 3245,
        "uniqueVisitors": 2156,
        "avgTimeOnPage": "2m 15s",
        "bounceRate": 38.2
      },
      {
        "url": "/pricing",
        "pageviews": 1876,
        "uniqueVisitors": 1543,
        "avgTimeOnPage": "4m 32s",
        "bounceRate": 28.5
      }
    ],
    "updatedAt": "2026-04-05T12:00:00Z"
  }'

Example Success Response:

{ "success": true }

POST /api/simbioza-analytics/traffic-sources

Updates traffic source breakdown data.

Body Schema:

{
  "period": "7d" | "30d" | "90d",
  "sources": [
    {
      "name": string,         // e.g., "Organic", "Direct", "Social"
      "sessions": number,
      "percentage": number    // Integer 0-100 (percentages should sum to 100)
    }
  ],
  "updatedAt": string         // ISO 8601 timestamp
}

Example Request:

curl -X POST https://dashboard.thesherminator.com/api/simbioza-analytics/traffic-sources \
  -H "Content-Type: application/json" \
  -d '{
    "period": "7d",
    "sources": [
      { "name": "Organic", "sessions": 2345, "percentage": 42 },
      { "name": "Direct", "sessions": 1567, "percentage": 28 },
      { "name": "Referral", "sessions": 892, "percentage": 16 },
      { "name": "Social", "sessions": 445, "percentage": 8 },
      { "name": "Email", "sessions": 223, "percentage": 4 },
      { "name": "Paid", "sessions": 111, "percentage": 2 }
    ],
    "updatedAt": "2026-04-05T12:00:00Z"
  }'

Example Success Response:

{ "success": true }

POST /api/simbioza-analytics/ai-insights

Updates AI-generated analysis and recommendations.

Body Schema:

{
  "agentName": string,            // Name of the agent generating insights
  "analysis": string,             // Markdown-formatted analysis text
  "recommendations": [
    {
      "priority": "high" | "medium" | "low",
      "text": string
    }
  ],
  "generatedAt": string           // ISO 8601 timestamp
}

Example Request:

curl -X POST https://dashboard.thesherminator.com/api/simbioza-analytics/ai-insights \
  -H "Content-Type: application/json" \
  -d '{
    "agentName": "Aria",
    "analysis": "**Key Observations:**\n\n• Traffic up 12% week-over-week\n• Bounce rate improved by 3 points\n• Pricing page shows strong engagement",
    "recommendations": [
      {
        "priority": "high",
        "text": "Launch weekend content campaign to capture 30-40% more traffic"
      },
      {
        "priority": "medium",
        "text": "Optimize /contact page - highest bounce rate at 52.3%"
      },
      {
        "priority": "low",
        "text": "Increase social media investment - currently only 8% of traffic"
      }
    ],
    "generatedAt": "2026-04-05T12:00:00Z"
  }'

Example Success Response:

{ "success": true }

POST /api/simbioza-analytics/alerts

Updates alerts and anomaly notifications.

Body Schema:

{
  "alerts": [
    {
      "id": string,                        // Unique alert ID
      "severity": "info" | "warning" | "critical",
      "message": string,
      "timestamp": string,                 // ISO 8601 timestamp
      "source": string                     // Source agent/system name
    }
  ]
}

Example Request:

curl -X POST https://dashboard.thesherminator.com/api/simbioza-analytics/alerts \
  -H "Content-Type: application/json" \
  -d '{
    "alerts": [
      {
        "id": "alert-1",
        "severity": "warning",
        "message": "Traffic spike +40% on /pricing page (last 2 hours)",
        "timestamp": "2026-04-05T12:00:00Z",
        "source": "Traffic Monitor"
      },
      {
        "id": "alert-2",
        "severity": "info",
        "message": "Mobile traffic increased to 58% (was 52% yesterday)",
        "timestamp": "2026-04-05T10:00:00Z",
        "source": "Device Tracker"
      }
    ]
  }'

Example Success Response:

{ "success": true }

4. Recommended Update Workflow

Step-by-step sequence for a complete analytics push:

Fetch and analyze source data
Pull data from Google Analytics, Plausible, or your analytics tool. Calculate metrics, trends, and comparisons.
Push Live KPIs first
POST to /api/simbioza-analytics/live-kpis with current metrics and trend data.
Push Traffic Chart data
POST to /api/simbioza-analytics/traffic-chart with 7d/30d/90d data (start with 7d).
Push Top Pages data
POST to /api/simbioza-analytics/top-pages with page performance metrics.
Push Traffic Sources data
POST to /api/simbioza-analytics/traffic-sources with source breakdown (7d/30d/90d).
Generate and push AI Insights
Analyze the data, generate insights, create prioritized recommendations, then POST to /api/simbioza-analytics/ai-insights.
Push Alerts (if any anomalies detected)
If you detect spikes, drops, or anomalies, POST to /api/simbioza-analytics/alerts. Otherwise, push an empty alerts array {"alerts": []}.

⚠️ Error Handling

If any POST request fails (non-200 response), log the error and retry up to 3 times with exponential backoff (2s, 4s, 8s). If all retries fail, alert the user and skip that section. Do not halt the entire workflow — continue pushing remaining sections.

✅ Success Verification

After pushing all data, verify by calling GET /api/simbioza-analytics/alland confirming all sections are populated correctly.

5. Field Definitions

Numeric Metrics

activeVisitors: Current count of active visitors on the site (real-time)
todaySessions: Total number of sessions started today (cumulative)
todayPageviews: Total pageviews today (cumulative)
goalConversions: Number of goal completions today (e.g., form submissions, signups)
pageviews: Total views for a specific page
uniqueVisitors: Unique visitor count for a specific page
sessions: Session count (used in traffic chart and sources)

Percentage Fields

bounceRate: Percentage of single-page sessions (0-100). Example: 42.5 means 42.5%
percentage: Traffic source share (0-100). All sources should sum to 100. Example: 42 means 42%

Time/Duration Fields

avgSessionDuration: Average session length.Format: "Xm Ys" (e.g., "3m 42s", "1m 15s")
avgTimeOnPage: Average time spent on a page.Format: "Xm Ys" (e.g., "2m 15s")
updatedAt, generatedAt, timestamp:ISO 8601 format (e.g., "2026-04-05T12:00:00Z")

Trend Data

The trends object shows percentage change vs yesterday. Positive = increase (green ↑), Negative = decrease (red ↓).

"trends": {
  "todaySessions": 8,     // +8% vs yesterday (green arrow)
  "bounceRate": -3        // -3% vs yesterday (red arrow, lower is better)
}

Period Options

For traffic chart and sources, period must be one of:

"7d" — Last 7 days
"30d" — Last 30 days
"90d" — Last 90 days

Alert Severity Levels

"info": Informational (blue icon)
"warning": Warning (yellow icon)
"critical": Critical (red icon)

Recommendation Priority Levels

"high": Urgent action needed (red badge)
"medium": Important but not urgent (yellow badge)
"low": Nice to have (green badge)

6. Tips & Best Practices

✅

Always push all sections in one update cycle

Don't push only KPIs and leave other sections stale. Update all 6 sections together to maintain data consistency.

✅

Recommended update frequency

Every 1-6 hours for live data. Daily for historical/trend analysis. Adjust based on traffic volume and user needs.

✅

Handle empty states gracefully

If no anomalies: push {"alerts": []}. If no traffic: still push zero values, not null. The dashboard shows "Waiting for agent data..." only when the entire section is missing.

✅

Use ISO 8601 timestamps consistently

Always use UTC timezone: "2026-04-05T12:00:00Z". This ensures consistent "last updated" displays.

✅

Make AI insights actionable

Analysis should explain why metrics changed. Recommendations should be specific (not "improve SEO" but "Add meta descriptions to top 10 pages").

❌

Do not leave partial data

Don't push KPIs without updating traffic chart/sources. Users will see mixed old+new data. Either update all sections or none.

❌

Do not use placeholder/fake data

Only push real analytics data. If data is unavailable, wait until you have it. The dashboard handles empty states gracefully.

💡 Pro Tip: Test Your Integration

Use the test script at /home/ubuntu/.openclaw/agents/frontend/command-center/test-analytics-data.shto see example payloads and verify the dashboard displays data correctly.

Questions or issues? Check the main documentation at /home/ubuntu/.openclaw/agents/frontend/command-center/SIMBIOZA-ANALYTICS-DOCS.md

← Back to Analytics Dashboard