Skip to main content

Streaming Analytics

The analytics API gives stream owners detailed insight into their audience — how many people watched, where they came from, how the chat behaved, and when viewers dropped off. All analytics endpoints require authentication and are restricted to the stream owner.

Get stream analytics​

GET /api/v1/streams/{stream_id}/analytics

Get comprehensive analytics for a stream. Includes total views, unique viewers, peak concurrent viewers, total watch time, and chat engagement.

Auth required: Yes (owner only)

Response​

{
  "stream_id": "a1b2c3d4-...",
  "total_views": 4832,
  "unique_viewers": 3201,
  "peak_concurrent_viewers": 892,
  "average_concurrent_viewers": 312,
  "total_watch_time_minutes": 18450,
  "chat_messages_total": 6721,
  "unique_chatters": 487
}

Returns 403 if the authenticated user is not the stream owner.

Get viewer timeline​

GET /api/v1/streams/{stream_id}/analytics/viewers

Get concurrent viewer count over time. Returns time-series data sampled at a configurable interval. Useful for plotting a viewership chart.

Auth required: Yes (owner only)

Query parameters​

ParameterTypeDefaultDescription
interval_minutesinteger5Sampling interval (1–60 minutes)

Response​

{
  "stream_id": "a1b2c3d4-...",
  "interval_minutes": 5,
  "timeline": [
    { "timestamp": "2026-04-25T10:00:00Z", "viewer_count": 23 },
    { "timestamp": "2026-04-25T10:05:00Z", "viewer_count": 87 },
    { "timestamp": "2026-04-25T10:10:00Z", "viewer_count": 312 },
    { "timestamp": "2026-04-25T10:15:00Z", "viewer_count": 891 }
  ]
}

Get chat statistics​

GET /api/v1/streams/{stream_id}/analytics/chat

Get chat engagement metrics for a stream.

Auth required: Yes (owner only)

Response​

{
  "total_messages": 6721,
  "unique_chatters": 487,
  "messages_per_minute": 22.4,
  "peak_messages_per_minute": 118,
  "most_active_chatters": [
    { "username": "bob", "message_count": 143 }
  ]
}

Get geographic breakdown​

GET /api/v1/streams/{stream_id}/analytics/geography

Get the geographic distribution of viewers by country. Raw IP addresses are never exposed — the platform uses SHA-256 IP hashing for privacy.

Auth required: Yes (owner only)

Response​

{
  "stream_id": "a1b2c3d4-...",
  "total_viewers": 3201,
  "breakdown": [
    { "country": "United States", "country_code": "US", "viewer_count": 1843, "percentage": 57.6 },
    { "country": "United Kingdom", "country_code": "GB", "viewer_count": 412, "percentage": 12.9 },
    { "country": "Germany", "country_code": "DE", "viewer_count": 201, "percentage": 6.3 }
  ]
}

Get engagement metrics​

GET /api/v1/streams/{stream_id}/analytics/engagement

Get detailed engagement analysis including follow conversion, chat participation rate, average and median watch time, returning viewer rate, viewer retention curve, and significant drop-off points.

Auth required: Yes (owner only)

Response​

{
  "follow_conversion_rate": 0.034,
  "chat_participation_rate": 0.152,
  "average_watch_time_minutes": 18.3,
  "median_watch_time_minutes": 11.7,
  "returning_viewer_rate": 0.28,
  "retention_curve": [
    { "minute": 0, "retention_percentage": 100 },
    { "minute": 5, "retention_percentage": 73 },
    { "minute": 15, "retention_percentage": 48 },
    { "minute": 30, "retention_percentage": 29 }
  ],
  "significant_drop_offs": [
    { "minute": 8, "drop_percentage": 12.4, "reason": "ad_break" }
  ]
}

Get analytics summary​

GET /api/v1/streams/{stream_id}/analytics/summary

Combines all analytics metrics into a single comprehensive dashboard view. Includes viewer stats, watch time, chat engagement, follow conversions, and the top 5 countries.

Auth required: Yes (owner only)

This is the recommended endpoint for building a full stream analytics dashboard — it avoids multiple round-trips.

Export analytics​

GET /api/v1/streams/{stream_id}/analytics/export

Export analytics data as a file download.

Auth required: Yes (owner only)

Query parameters​

ParameterTypeDefaultDescription
formatstringjsonExport format: json or csv
FormatContent-TypeFilename
jsonapplication/jsonstream_{id}_analytics.json
csvtext/csvstream_{id}_analytics.csv

The response is delivered as an attachment with a Content-Disposition header. CSV format is suitable for analysis in Excel or Google Sheets.

# Download as CSV
curl -O -J \
  "https://api.ainative.studio/api/v1/streams/a1b2c3d4-.../analytics/export?format=csv" \
  -H "Authorization: Bearer $API_KEY"

Channel-level analytics​

These endpoints return analytics aggregated across all streams for a channel, not just a single stream.

Peak concurrent viewers​

Returns the highest concurrent viewer count ever recorded for the channel.

Session analytics​

Returns per-session metrics — useful for comparing performance across streams.

Notes on data collection​

  • Viewer sessions are tracked anonymously via hashed IP addresses (SHA-256)
  • Viewer count updates are sampled periodically, not real-time per connection
  • Chat statistics are computed from persisted message records
  • Geographic data is derived from viewer IP addresses using GeoIP lookup; raw IPs are never stored or exposed