Analytics & Quality Score

Surflet provides page-level view analytics and tenant-level agent quality scoring to help you understand how pages are used and how effective your agent's output is.

Page Analytics

GET /v1/pages/:id/analytics

Retrieve view statistics for a specific page.

Response (200):

{
  "pageId": "pg_abc123",
  "totalViews": 47,
  "uniqueViewers": 12,
  "dailyViews": {
    "2026-03-20": 15,
    "2026-03-21": 18,
    "2026-03-22": 8,
    "2026-03-23": 6
  },
  "createdAt": "2026-03-20T10:00:00Z",
  "status": "active"
}

Field	Type	Description
totalViews	number	Total view count
uniqueViewers	number	Unique visitor count
dailyViews	object	Daily views keyed by date
createdAt	string	Page creation time
status	string	Current page status

How Views Are Recorded

Page views are recorded automatically when the page loads — no additional configuration required:

1. User opens the page URL
2. The renderer automatically calls the internal endpoint POST /internal/pages/:id/view
3. Redis atomically updates the view counter and unique visitor set
4. Daily views are bucketed by date

Atomic counting is implemented with Redis HINCRBY; unique visitor deduplication uses SADD (based on a hash of IP + User-Agent).

Python SDK

import surflet

client = surflet.Client(api_key="sk_live_...")

# Get page analytics
analytics = client.get_analytics("pg_abc123")
print(f"Total views: {analytics['totalViews']}")
print(f"Unique viewers: {analytics['uniqueViewers']}")

for date, views in analytics["dailyViews"].items():
    print(f"  {date}: {views} views")

TypeScript SDK

const analytics = await client.getAnalytics('pg_abc123');
console.log(`Total views: ${analytics.totalViews}`);
console.log(`Unique viewers: ${analytics.uniqueViewers}`);

MCP Tool

[surflet_get_analytics]
page_id: "pg_abc123"

→ { totalViews: 47, uniqueViewers: 12, dailyViews: { ... } }

---

Agent Quality Score

GET /v1/quality-score

Retrieve the agent quality score for the current tenant. The score is calculated from decision data across the most recent 100 pages.

Response (200):

{
  "tenantId": "tn_xxx",
  "totalPages": 87,
  "totalDecisions": 72,
  "acceptanceRate": 89,
  "avgDecisionTimeMinutes": 35,
  "score": 78,
  "period": "last_100_pages"
}

Field	Type	Description
totalPages	number	Total pages analyzed (most recent 100)
totalDecisions	number	Pages with a decision outcome
acceptanceRate	number	Acceptance rate (0–100, percentage)
avgDecisionTimeMinutes	number	Average decision time (minutes)
score	number	Composite quality score (0–100)
period	string	Description of the measurement period

Scoring Algorithm

The quality score is a weighted calculation of two factors:

score = acceptance_rate * 70% + decision_speed * 30%

• Acceptance Rate (70% weight): the ratio of accepted (completed) to rejected (revoked) pages. A high acceptance rate indicates strong recommendation quality from the agent.
• Decision Speed (30% weight): the average time from page publish to completion. Faster decisions indicate that pages are clearly structured with sufficient information for users to decide quickly. Decision times exceeding 24 hours score 0 on this factor.

Use Cases

• Agent tuning: monitor quality score changes to optimize your agent's recommendation logic
• Operations dashboard: display agent efficiency metrics in your internal dashboard
• Alerting: trigger alerts when acceptance rate drops or decision time increases

Python SDK

score = client.get_quality_score()
print(f"Quality Score: {score['score']}/100")
print(f"Acceptance Rate: {score['acceptanceRate']}%")
print(f"Avg Decision Time: {score['avgDecisionTimeMinutes']} minutes")

TypeScript SDK

const score = await client.getQualityScore();
console.log(`Quality Score: ${score.score}/100`);
console.log(`Acceptance Rate: ${score.acceptanceRate}%`);