---
title: "Streaming Analytics"
description: "Real-time streaming analytics — viewer counts, engagement metrics, and quality monitoring"
canonical: "https://docs.ainative.studio/docs/live-streaming/analytics"
last-updated: "2026-10-22T17:48:46.689Z"
---

# Streaming Analytics

Source: https://docs.ainative.studio/docs/live-streaming/analytics

> Real-time streaming analytics — viewer counts, engagement metrics, and quality monitoring

## 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

<span className="badge badge--get">GET</span> `/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

```json
{
  "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

<span className="badge badge--get">GET</span> `/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

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `interval_minutes` | integer | `5` | Sampling interval (1–60 minutes) |

### Response

```json
{
  "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

<span className="badge badge--get">GET</span> `/api/v1/streams/{stream_id}/analytics/chat`

Get chat engagement metrics for a stream.

**Auth required:** Yes (owner only)

### Response

```json
{
  "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

<span className="badge badge--get">GET</span> `/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

```json
{
  "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

<span className="badge badge--get">GET</span> `/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

```json
{
  "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

<span className="badge badge--get">GET</span> `/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

<span className="badge badge--get">GET</span> `/api/v1/streams/{stream_id}/analytics/export`

Export analytics data as a file download.

**Auth required:** Yes (owner only)

### Query parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `format` | string | `json` | Export format: `json` or `csv` |

| Format | Content-Type | Filename |
|--------|-------------|----------|
| `json` | `application/json` | `stream_{id}_analytics.json` |
| `csv` | `text/csv` | `stream_{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.

```bash
## 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