Skip to content

Analytics API

The Analytics API provides programmatic access to analytics data, metrics, and reports.

Base URL

https://smailander.com/api/v1/analytics

Authentication

All API endpoints require authentication. See Authentication for details.

Endpoints

Get Analytics Overview

Retrieve high-level analytics overview.

GET /api/v1/analytics/overview

Query Parameters:

Parameter Type Required Description
period string No Time period: 24h, 7d, 30d, 90d, 365d, custom
start_date string No Start date (ISO 8601) - required if period=custom
end_date string No End date (ISO 8601) - required if period=custom
compare boolean No Compare with previous period

Response:

{
  "period": "30d",
  "start_date": "2026-02-11T00:00:00Z",
  "end_date": "2026-03-12T23:59:59Z",
  "metrics": {
    "total_emails": 12847,
    "threats_detected": 8590,
    "detection_rate": 0.92,
    "malware_count": 2955,
    "spam_count": 5790,
    "phishing_count": 2750
  },
  "comparison": {
    "total_emails_change": 15.0,
    "threats_detected_change": 12.0,
    "detection_rate_change": 1.0
  }
}

Get Threat Distribution

Get breakdown of threats by type.

GET /api/v1/analytics/threat-distribution

Query Parameters:

Parameter Type Required Description
period string No Time period (default: 30d)
group_by string No Group by: type, score, severity

Response:

{
  "data": [
    {
      "type": "spam",
      "count": 5790,
      "percentage": 0.45,
      "trend": "up"
    },
    {
      "type": "phishing",
      "count": 2750,
      "percentage": 0.32,
      "trend": "up"
    },
    {
      "type": "malware",
      "count": 2955,
      "percentage": 0.23,
      "trend": "up"
    }
  ]
}

Get Geographic Data

Get threat distribution by geographic location.

GET /api/v1/analytics/geographic

Query Parameters:

Parameter Type Required Description
period string No Time period
limit integer No Number of results (default: 10)

Response:

{
  "data": [
    {
      "country": "Russia",
      "code": "RU",
      "threats": 2341,
      "percentage": 27.2,
      "trend": "up"
    },
    {
      "country": "China",
      "code": "CN",
      "threats": 1567,
      "percentage": 18.2,
      "trend": "stable"
    }
  ]
}

Get Honeypot Analytics

Get analytics for specific honeypots.

GET /api/v1/analytics/honeypots

Query Parameters:

Parameter Type Required Description
honeypot_id string No Specific honeypot ID
period string No Time period

Response:

{
  "honeypots": [
    {
      "email": "monitor@company.com",
      "emails": 3456,
      "threats": 2890,
      "threat_rate": 0.84,
      "top_threat": "spam",
      "status": "active"
    }
  ]
}

Get Time Series Data

Get analytics data over time.

GET /api/v1/analytics/timeseries

Query Parameters:

Parameter Type Required Description
metric string Yes Metric to retrieve
period string No Time period
interval string No Interval: hour, day, week, month

Response:

{
  "metric": "total_emails",
  "interval": "day",
  "data": [
    {
      "timestamp": "2026-02-11T00:00:00Z",
      "value": 428
    },
    {
      "timestamp": "2026-02-12T00:00:00Z",
      "value": 445
    }
  ]
}

Export Analytics

Export analytics data in various formats.

GET /api/v1/analytics/export

Query Parameters:

Parameter Type Required Description
format string Yes csv, json, xlsx
period string No Time period
filters string No JSON-encoded filters

Response:

Returns the exported file in the specified format.

Rate Limits

  • Standard: 100 requests per minute
  • Premium: 1000 requests per minute

Errors

See Error Codes for details.

Next Steps