Analytics API

The Analytics module provides real-time business intelligence — revenue dashboards, conversion funnels, inventory KPIs, HR metrics, support performance, and AI-powered forecasting. Data is aggregated server-side and returned in chart-ready formats.

---

Endpoints

Method	Path	Description
GET	/api/analytics/revenue	Revenue metrics (time-series)
GET	/api/analytics/sales	Sales funnel and pipeline
GET	/api/analytics/products	Product performance
GET	/api/analytics/customers	Customer acquisition and LTV
GET	/api/analytics/inventory	Inventory health metrics
GET	/api/analytics/hr	HR headcount and attendance
GET	/api/analytics/support	Helpdesk KPIs
GET	/api/analytics/marketing	Campaign and email metrics
GET	/api/analytics/forecast	AI revenue forecast
GET	/api/analytics/anomalies	Detected metric anomalies
GET	/api/analytics/dashboards	List saved dashboards
POST	/api/analytics/reports/export	Export report to Excel/CSV

---

Common Query Parameters

All analytics endpoints accept these parameters:

Parameter	Type	Description
from	ISO 8601	Period start date
to	ISO 8601	Period end date
groupBy	day | week | month | quarter	Time aggregation
currency	string	Currency for monetary values (default: usd)

---

Revenue Metrics

GET /api/analytics/revenue?from=2026-01-01&to=2026-03-31&groupBy=month

Response

{
  "summary": {
    "totalRevenue": 3780000,
    "revenueGrowth": 0.23,
    "mrr": 1280000,
    "arr": 15360000,
    "avgOrderValue": 54000,
    "currency": "usd"
  },
  "timeSeries": [
    { "period": "2026-01", "revenue": 980000, "orders": 18, "refunds": 15000 },
    { "period": "2026-02", "revenue": 1240000, "orders": 23, "refunds": 0 },
    { "period": "2026-03", "revenue": 1560000, "orders": 29, "refunds": 49900 }
  ],
  "byProduct": [
    { "productName": "Shopify Connector", "revenue": 1498000, "units": 30 },
    { "productName": "Amazon Connector", "revenue": 998000, "units": 20 }
  ]
}

---

Sales Funnel

GET /api/analytics/sales?from=2026-01-01&to=2026-03-31

Response

{
  "funnel": [
    { "stage": "leads", "count": 420, "value": 20580000 },
    { "stage": "qualified", "count": 210, "value": 10290000 },
    { "stage": "proposal", "count": 95, "value": 4655000 },
    { "stage": "negotiation", "count": 48, "value": 2352000 },
    { "stage": "won", "count": 70, "value": 3430000 }
  ],
  "winRate": 0.167,
  "avgDealSize": 49000,
  "avgCycledays": 18
}

---

Customer Metrics

GET /api/analytics/customers?from=2026-01-01&to=2026-03-31

Response

{
  "newCustomers": 48,
  "churnedCustomers": 3,
  "netGrowth": 45,
  "avgLtv": 298000,
  "cac": 12000,
  "ltvCacRatio": 24.8,
  "retentionRate": 0.94,
  "byAcquisitionChannel": [
    { "channel": "organic_search", "customers": 22, "percent": 0.46 },
    { "channel": "direct", "customers": 14, "percent": 0.29 },
    { "channel": "referral", "customers": 12, "percent": 0.25 }
  ]
}

---

AI Revenue Forecast

Uses historical data and seasonality patterns to project future revenue.

GET /api/analytics/forecast?periods=3&granularity=month

Response

{
  "model": "linear_regression_with_seasonality",
  "generatedAt": "2026-03-20T12:00:00Z",
  "forecast": [
    {
      "period": "2026-04",
      "predicted": 1820000,
      "confidenceLow": 1650000,
      "confidenceHigh": 1990000
    },
    {
      "period": "2026-05",
      "predicted": 2050000,
      "confidenceLow": 1840000,
      "confidenceHigh": 2260000
    },
    {
      "period": "2026-06",
      "predicted": 2340000,
      "confidenceLow": 2090000,
      "confidenceHigh": 2590000
    }
  ],
  "confidence": 0.87,
  "currency": "usd"
}

---

Anomaly Detection

Returns metrics that have deviated significantly from their historical baseline.

GET /api/analytics/anomalies?severity=high

Query Parameters

Parameter	Type	Description
severity	low | medium | high	Minimum severity level
metric	string	Filter by metric name

Response

{
  "anomalies": [
    {
      "metric": "daily_revenue",
      "severity": "high",
      "detectedAt": "2026-03-19T23:00:00Z",
      "expected": 52000,
      "actual": 12000,
      "deviation": -0.77,
      "description": "Revenue 77% below 30-day moving average on 2026-03-19"
    }
  ]
}

---

Export Report

POST /api/analytics/reports/export
Content-Type: application/json

{
  "reportType": "revenue",
  "from": "2026-01-01",
  "to": "2026-03-31",
  "format": "xlsx",
  "groupBy": "month"
}

Returns a binary file stream (Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet for Excel, text/csv for CSV).

curl -o report_q1_2026.xlsx \
  -X POST \
  -H "Authorization: Bearer eco_live_..." \
  -H "Content-Type: application/json" \
  -d '{"reportType":"revenue","from":"2026-01-01","to":"2026-03-31","format":"xlsx","groupBy":"month"}' \
  https://api.ecosire.com/api/analytics/reports/export

Export formats: xlsx, csv

---

Status Codes

Code	Scenario
200	Metrics returned or export file served
400	Invalid date range or unknown groupBy
404	Dashboard or report not found
422	from date is after to date