Eve library

Business Metrics API Reference

Guide

Revision 1

On this page

Base URL#

text
https://api.lilith.platform/observability/v1/metrics

Authentication#

All metrics endpoints require valid service or user authentication.

bash
export LILITH_TOKEN="your-api-token"
curl -H "Authorization: Bearer $LILITH_TOKEN" \
     ${API_BASE}/metrics/dashboards/business

Endpoints#

Business Dashboard#

http
GET /v1/metrics/dashboards/business
Authorization: Bearer <token>

Returns comprehensive business KPI dashboard with real-time metrics.

Response Example:

json
{
  "dashboard_type": "business",
  "generated_at": "2024-01-01T12:00:00Z",
  "kpis": {
    "user_engagement": { "dau": 2847, "wau": 15632, "mau": 45891 },
    "conversion": { "signup_conversion_24h": 3.2 },
    "revenue": { "revenue_30d_usd": 127849.50 }
  }
}

Business Reports#

http
GET /v1/metrics/reports/business?period={period}&format={format}
Authorization: Bearer <token>

Parameters:

  • period: 7d | 30d | 90d | 1y
  • format: json | csv | pdf

Response Example:

json
{
  "report_type": "business_kpi",
  "period": "30d",
  "generated_at": "2024-01-01T12:00:00Z",
  "kpis": {
    "summary": {
      "dau_avg": 2654,
      "mau_growth": 23.1,
      "revenue_total": 127849.50
    },
    "trends": [
      {"date": "2024-01-01", "dau": 2847, "revenue": 4251.50},
      {"date": "2024-01-02", "dau": 2793, "revenue": 4184.20}
    ]
  },
  "insights": [
    {
      "category": "user_growth",
      "insight": "DAU growth accelerating (+12.5% vs +8.1% previous period)",
      "recommendation": "Continue current user acquisition strategy"
    }
  ]
}

KPI Historical Data#

http
GET /v1/metrics/kpis/{kpi_name}/history?period={period}&granularity={granularity}
Authorization: Bearer <token>

Parameters:

  • kpi_name: Any valid KPI (e.g., dau, conversion_rate, revenue_30d)
  • period: Time range (7d, 30d, 90d)
  • granularity: Data points (hour, day, week)

Real-time Metrics#

http
GET /v1/metrics/realtime?kpis={kpi_list}
Authorization: Bearer <token>

Example:

bash
curl "$API_BASE/metrics/realtime?kpis=dau,conversion_rate,revenue_30d"

Data Sources#

Analytics Events#

All KPIs are calculated from analytics events ingested via:

http
POST /v1/analytics/events
Content-Type: application/json
Authorization: Bearer <token>

{
  "event_type": "session.started",
  "user_hash": "sha256_hash_of_user_id",
  "session_id": "ses_1234567890",
  "timestamp": "2024-01-01T12:00:00Z",
  "context": {
    "platform": "web",
    "user_agent": "Mozilla/5.0...",
    "referrer": "https://google.com"
  },
  "consent": true
}

Event Schema Validation#

All analytics events must conform to the schema:

javascript
const eventSchema = {
  event_type: {
    type: 'string',
    required: true,
    enum: [
      'session.started', 'session.ended',
      'signup.started', 'signup.completed',
      'chat.message_sent', 'chat.session_ended',
      'voice.session_started', 'voice.session_ended',
      'meditation.started', 'meditation.completed',
      'payment.started', 'payment.completed'
    ]
  },
  user_hash: { type: 'string', pattern: /^[a-f0-9]{64}$/ },
  session_id: { type: 'string', required: true },
  timestamp: { type: 'string', format: 'iso8601' },
  consent: { type: 'boolean', required: true }
};

Error Handling#

Common Errors#

Status Error Description
400 invalid_period Invalid time period specified
401 unauthorized Missing or invalid authentication
403 insufficient_permissions Insufficient access permissions
404 kpi_not_found Requested KPI does not exist
429 rate_limited Too many requests
500 calculation_error Error calculating KPI

Error Response Format#

json
{
  "error": {
    "code": "invalid_period",
    "message": "Period must be one of: 7d, 30d, 90d, 1y",
    "details": {
      "provided": "invalid_period",
      "valid_options": ["7d", "30d", "90d", "1y"]
    }
  }
}

Generated automatically by business-metrics-docs-generator.js Last updated: 2025-09-26T09:29:19.730Z