Analytics

The Analytics API provides access to aggregated metrics for content performance, user engagement, and playback quality.

Endpoints

Method	Endpoint	Description
`GET`	`/v1/analytics/overview`	High-level metrics summary
`GET`	`/v1/analytics/content`	Content-level metrics
`GET`	`/v1/analytics/content/{id}`	Single content metrics
`GET`	`/v1/analytics/engagement`	Engagement metrics
`GET`	`/v1/analytics/quality`	Playback quality metrics
`GET`	`/v1/analytics/retention`	User retention data

Overview metrics

Get a high-level summary of key metrics.

GET /v1/analytics/overview

Query parameters

startDate

string

required

Start date (ISO 8601: YYYY-MM-DD).

endDate

string

required

End date (ISO 8601: YYYY-MM-DD).

granularity

string

default:"day"

Time granularity: hour, day, week.

Example request

curl "https://api.shortkit.dev/v1/analytics/overview?startDate=2024-01-01&endDate=2024-01-31" \
  -H "Authorization: Bearer sk_live_your_secret_key"

Response

{
  "data": {
    "summary": {
      "totalImpressions": 1250000,
      "totalPlays": 980000,
      "totalCompletions": 420000,
      "uniqueViewers": 85000,
      "averageWatchTime": 28.5,
      "completionRate": 0.428,
      "engagementRate": 0.784
    },
    "timeseries": [
      {
        "date": "2024-01-01",
        "impressions": 42000,
        "plays": 33000,
        "completions": 14000,
        "uniqueViewers": 8500
      }
    ],
    "comparison": {
      "impressions": { "change": 0.12, "direction": "up" },
      "plays": { "change": 0.08, "direction": "up" },
      "completions": { "change": -0.02, "direction": "down" }
    }
  },
  "meta": {
    "dateRange": {
      "start": "2024-01-01",
      "end": "2024-01-31"
    },
    "comparisonPeriod": {
      "start": "2023-12-01",
      "end": "2023-12-31"
    }
  }
}

Content analytics

Get metrics for all content or a specific item.

List content metrics

GET /v1/analytics/content

startDate

string

required

Start date.

endDate

string

required

End date.

limit

integer

default:20

Items per page (1-100).

cursor

string

Pagination cursor.

sort

string

default:"impressions"

Sort field: impressions, plays, completions, watchTime.

order

string

default:"desc"

Sort order: asc, desc.

Example request

curl "https://api.shortkit.dev/v1/analytics/content?startDate=2024-01-01&endDate=2024-01-31&sort=completions&limit=10" \
  -H "Authorization: Bearer sk_live_your_secret_key"

Response

{
  "data": [
    {
      "contentId": "cnt_abc123",
      "title": "Product Launch Video",
      "metrics": {
        "impressions": 45000,
        "plays": 38000,
        "completions": 18000,
        "totalWatchTime": 684000,
        "averageWatchTime": 38.0,
        "completionRate": 0.474,
        "likes": 2400,
        "shares": 850,
        "saves": 320
      }
    }
  ],
  "meta": {
    "total": 150,
    "nextCursor": "eyJvZmZzZXQiOjIwfQ=="
  }
}

Single content metrics

GET /v1/analytics/content/{id}

string

required

Content ID.

startDate

string

required

Start date.

endDate

string

required

End date.

granularity

string

default:"day"

Time granularity.

Example request

curl "https://api.shortkit.dev/v1/analytics/content/cnt_abc123?startDate=2024-01-01&endDate=2024-01-31" \
  -H "Authorization: Bearer sk_live_your_secret_key"

Response

{
  "data": {
    "contentId": "cnt_abc123",
    "title": "Product Launch Video",
    "summary": {
      "impressions": 45000,
      "plays": 38000,
      "completions": 18000,
      "uniqueViewers": 32000,
      "totalWatchTime": 684000,
      "averageWatchTime": 38.0,
      "completionRate": 0.474
    },
    "timeseries": [
      {
        "date": "2024-01-01",
        "impressions": 2500,
        "plays": 2100,
        "completions": 1000
      }
    ],
    "demographics": {
      "deviceTypes": {
        "ios": 0.45,
        "android": 0.40,
        "web": 0.15
      },
      "countries": {
        "US": 0.35,
        "GB": 0.15,
        "CA": 0.10
      }
    },
    "engagement": {
      "averagePercentWatched": 0.72,
      "dropoffPoints": [
        { "second": 5, "retained": 0.95 },
        { "second": 15, "retained": 0.78 },
        { "second": 30, "retained": 0.52 }
      ]
    }
  }
}

Engagement analytics

Detailed engagement metrics across content.

GET /v1/analytics/engagement

Query parameters

startDate

string

required

Start date.

endDate

string

required

End date.

granularity

string

default:"day"

Time granularity.

segment

string

Segment by: device, country, topic.

Example request

curl "https://api.shortkit.dev/v1/analytics/engagement?startDate=2024-01-01&endDate=2024-01-31&segment=device" \
  -H "Authorization: Bearer sk_live_your_secret_key"

Response

{
  "data": {
    "summary": {
      "totalSessions": 125000,
      "averageSessionLength": 8.5,
      "averageVideosPerSession": 12,
      "averageWatchTimePerSession": 342
    },
    "segments": {
      "ios": {
        "sessions": 56000,
        "averageSessionLength": 9.2,
        "completionRate": 0.48
      },
      "android": {
        "sessions": 50000,
        "averageSessionLength": 8.1,
        "completionRate": 0.42
      },
      "web": {
        "sessions": 19000,
        "averageSessionLength": 6.8,
        "completionRate": 0.38
      }
    },
    "timeseries": [
      {
        "date": "2024-01-01",
        "sessions": 4200,
        "averageVideosPerSession": 11.5
      }
    ]
  }
}

Quality analytics

Playback quality and performance metrics.

GET /v1/analytics/quality

Query parameters

startDate

string

required

Start date.

endDate

string

required

End date.

granularity

string

default:"day"

Time granularity.

Example request

curl "https://api.shortkit.dev/v1/analytics/quality?startDate=2024-01-01&endDate=2024-01-31" \
  -H "Authorization: Bearer sk_live_your_secret_key"

Response

{
  "data": {
    "summary": {
      "averageStartupTime": 285,
      "rebufferRate": 0.012,
      "averageRebufferDuration": 1.8,
      "errorRate": 0.003,
      "averageBitrate": 2850000
    },
    "renditionDistribution": {
      "1080p": 0.25,
      "720p": 0.45,
      "480p": 0.20,
      "360p": 0.10
    },
    "codecDistribution": {
      "h264": 0.65,
      "av1": 0.35
    },
    "errors": {
      "MEDIA_ERR_NETWORK": 42,
      "MEDIA_ERR_DECODE": 18,
      "MEDIA_ERR_SRC_NOT_SUPPORTED": 5
    },
    "timeseries": [
      {
        "date": "2024-01-01",
        "startupTime": 290,
        "rebufferRate": 0.015,
        "errorRate": 0.004
      }
    ]
  }
}

Retention analytics

User retention and cohort analysis.

GET /v1/analytics/retention

Query parameters

startDate

string

required

Cohort start date.

endDate

string

required

Cohort end date.

period

string

default:"day"

Retention period: day, week, month.

Example request

curl "https://api.shortkit.dev/v1/analytics/retention?startDate=2024-01-01&endDate=2024-01-07&period=day" \
  -H "Authorization: Bearer sk_live_your_secret_key"

Response

{
  "data": {
    "cohorts": [
      {
        "date": "2024-01-01",
        "size": 5200,
        "retention": [1.0, 0.45, 0.32, 0.28, 0.25, 0.23, 0.21]
      },
      {
        "date": "2024-01-02",
        "size": 4800,
        "retention": [1.0, 0.42, 0.30, 0.26, 0.24, 0.22]
      }
    ],
    "summary": {
      "day1Retention": 0.44,
      "day7Retention": 0.21,
      "day30Retention": 0.12
    }
  }
}

Real-time analytics

Get near-real-time metrics (updated every minute).

GET /v1/analytics/realtime

Example request

curl https://api.shortkit.dev/v1/analytics/realtime \
  -H "Authorization: Bearer sk_live_your_secret_key"

Response

{
  "data": {
    "activeViewers": 1250,
    "playsPerMinute": 420,
    "impressionsPerMinute": 580,
    "topContent": [
      { "contentId": "cnt_abc123", "activeViewers": 85 },
      { "contentId": "cnt_def456", "activeViewers": 72 }
    ],
    "geoDistribution": {
      "US": 450,
      "GB": 180,
      "DE": 120
    }
  },
  "meta": {
    "timestamp": "2024-02-04T12:00:00Z"
  }
}

SDK examples

JavaScript
Python

import { ShortkitAdmin } from '@shortkit/node';

const shortkit = new ShortkitAdmin({ apiKey: 'sk_live_...' });

// Get overview
const overview = await shortkit.analytics.overview({
  startDate: '2024-01-01',
  endDate: '2024-01-31'
});

// Get content metrics
const contentMetrics = await shortkit.analytics.content('cnt_abc123', {
  startDate: '2024-01-01',
  endDate: '2024-01-31'
});

// Get quality metrics
const quality = await shortkit.analytics.quality({
  startDate: '2024-01-01',
  endDate: '2024-01-31'
});

from shortkit import ShortkitAdmin

shortkit = ShortkitAdmin(api_key='sk_live_...')

# Get overview
overview = shortkit.analytics.overview(
    start_date='2024-01-01',
    end_date='2024-01-31'
)

# Get content metrics
content_metrics = shortkit.analytics.content(
    'cnt_abc123',
    start_date='2024-01-01',
    end_date='2024-01-31'
)

# Get quality metrics
quality = shortkit.analytics.quality(
    start_date='2024-01-01',
    end_date='2024-01-31'
)

Data availability

Metric Type	Latency	Retention
Real-time	~1 minute	24 hours
Aggregated	~1 hour	2 years
Raw events	N/A	90 days

Overview

Content

Feed

Configuration

Analytics

Endpoints

Overview metrics

Query parameters

Example request

Response

Content analytics

List content metrics

Example request

Response

Single content metrics

Example request

Response

Engagement analytics

Query parameters

Example request

Response

Quality analytics

Query parameters

Example request

Response

Retention analytics

Query parameters

Example request

Response

Real-time analytics

Example request

Response

SDK examples

Data availability

Next steps

Data export

Analytics dashboard

Overview

Content

Feed

Analytics

Configuration

​Endpoints

​Overview metrics

​Query parameters

​Example request

​Response

​Content analytics

​List content metrics

​Example request

​Response

​Single content metrics

​Example request

​Response

​Engagement analytics

​Query parameters

​Example request

​Response

​Quality analytics

​Query parameters

​Example request

​Response

​Retention analytics

​Query parameters

​Example request

​Response

​Real-time analytics

​Example request

​Response

​SDK examples

​Data availability

​Next steps

Data export

Analytics dashboard

Endpoints

Overview metrics

Query parameters

Example request

Response

Content analytics

List content metrics

Example request

Response

Single content metrics

Example request

Response

Engagement analytics

Query parameters

Example request

Response

Quality analytics

Query parameters

Example request

Response

Retention analytics

Query parameters

Example request

Response

Real-time analytics

Example request

Response

SDK examples

Data availability

Next steps