Metrics

The Creators API returns two optional metric objects per channel: engagement metrics and video metrics. Both are requested via the include query parameter and returned per-channel in the response.

# Request both metric types
curl "https://api.upriver.ai/v1/creators/profile-by-url?\
url=https://youtube.com/@example&\
include=engagement_metrics,video_metrics" \
  -H "X-API-Key: YOUR_KEY"

Engagement Metrics

Engagement metrics summarize a creator’s recent content performance — average views, likes, comments, and an overall engagement rate.

Fields

Field	Type	Description
`avg_views`	`integer \| null`	Average view count across recent content
`avg_likes`	`integer \| null`	Average like count across recent content
`avg_comments`	`integer \| null`	Average comment count across recent content
`avg_engagement_rate`	`float \| null`	`(likes + comments) / views`, expressed as a decimal (e.g., 0.05 = 5%)

Platform Coverage

Engagement metrics are available on these platforms:

Platform	Content Types Sampled	Metrics Available
YouTube	Videos, Shorts	Views, Likes, Comments
Instagram	Posts, Reels	Views (reels), Likes, Comments
TikTok	Videos	Views, Likes, Comments
X (Twitter)	Posts	Views, Likes, Comments
Twitch	Videos, Clips	Views only

Platforms not listed above (Substack, Spotify, Podcast) return channel metadata but do not include engagement metrics.

How Calculation Works

Engagement metrics are computed from a creator’s recent posts per content type on each platform.

Fetch recent content

Recent items are collected per content type — for example, YouTube Videos and Shorts are sampled separately.

Average per content type

Within each content type, metrics are averaged independently — average views, average likes, and average comments for that type alone.

Weighted average across content types

When a creator has multiple content types (e.g., both Videos and Shorts), the per-type averages are combined using a sample-size-weighted average.

avg_views = (videos_avg_views * videos_sample_size + shorts_avg_views * shorts_sample_size)
            / (videos_sample_size + shorts_sample_size)

This keeps content types with more samples proportionally weighted.

Derive engagement rate

Once the weighted averages are computed:

avg_engagement_rate = (avg_likes + avg_comments) / avg_views

This is only calculated when avg_views > 0 and at least one of avg_likes or avg_comments is available.

Example

A YouTube creator who publishes both long-form videos and Shorts:

Content Type	Sample Size	Avg Views	Avg Likes
Videos	10	100,000	4,000
Shorts	15	50,000	2,500

Weighted avg_views = (100,000 * 10 + 50,000 * 15) / (10 + 15) = 70,000 Weighted avg_likes = (4,000 * 10 + 2,500 * 15) / (10 + 15) = 3,100 The Shorts pull the averages down because there are more of them — which reflects that this creator’s audience engages with Shorts differently than long-form videos.

Response Example

{
  "channels": [
    {
      "platform": "youtube",
      "handle": "@example",
      "engagement_metrics": {
        "avg_views": 70000,
        "avg_likes": 3100,
        "avg_comments": 850,
        "avg_engagement_rate": 0.056
      }
    }
  ]
}

Video Metrics

Video metrics describe a creator’s upload cadence and video duration profile over a trailing window. These are designed for ad inventory estimation — understanding how frequently a creator uploads, how long their videos are, and what percentage are eligible for mid-roll ads.

Video metrics are currently available for YouTube only.

Fields

Field	Type	Description
`avg_duration_seconds`	`integer \| null`	Average video duration in seconds within the lookback window
`uploads_per_week`	`float \| null`	Average uploads per week over the lookback window
`pct_over_8m`	`float \| null`	Percentage of videos over 8 minutes (eligible for mid-roll ads)
`lookback_weeks`	`integer \| null`	Lookback window length (currently fixed at 12 weeks)
`weeks_observed`	`integer \| null`	How many weeks of history were actually observed
`window_complete`	`boolean \| null`	`true` when a full lookback window was observed

Lookback Window

Video metrics use a trailing 12-week window from the current date. All uploads published within this window are included in the calculation.

|<------------ 12 weeks ------------>|
|                                     now
|  uploads in this range are counted  |

Coverage Metadata

The weeks_observed and window_complete fields tell you how much history was available:

Scenario	`weeks_observed`	`window_complete`	Interpretation
Established creator	12	`true`	Full 12-week window observed
New creator (2 weeks old)	2	`false`	Only 2 weeks of history exist
Inactive creator (no uploads)	12	`true`	Full window, but 0 uploads

When window_complete is false, treat uploads_per_week as a preliminary estimate based on limited history. The creator may not have been active long enough for the metric to stabilize.

Mid-Roll Eligibility

pct_over_8m represents the percentage of videos in the window that are longer than 8 minutes (480 seconds). YouTube allows mid-roll ad breaks on videos over 8 minutes, making this a useful signal for ad inventory planning.

Response Examples

Established creator with consistent uploads

{
  "video_metrics": {
    "avg_duration_seconds": 615,
    "uploads_per_week": 1.75,
    "pct_over_8m": 66.7,
    "lookback_weeks": 12,
    "weeks_observed": 12,
    "window_complete": true
  }
}

Full 12 weeks observed. About 1.75 uploads/week, averaging ~10 minutes, with two-thirds of videos eligible for mid-roll ads.

New creator with limited history

{
  "video_metrics": {
    "avg_duration_seconds": 420,
    "uploads_per_week": 2.5,
    "pct_over_8m": 25.0,
    "lookback_weeks": 12,
    "weeks_observed": 2,
    "window_complete": false
  }
}

Only 2 weeks of upload history exist. Metrics are calculated over those 2 weeks — the upload rate may not be representative of long-term behavior.

Inactive creator (no uploads in window)

{
  "video_metrics": {
    "uploads_per_week": 0.0,
    "lookback_weeks": 12,
    "weeks_observed": 12,
    "window_complete": true
  }
}

Full window was observed, but no uploads fell within it. Duration and mid-roll fields are omitted.

Engagement vs. Video Metrics

These two metric types answer different questions:

	Engagement Metrics	Video Metrics
Question answered	How does this creator’s content perform?	How often and how long does this creator publish?
Platforms	YouTube, Instagram, TikTok, X, Twitch	YouTube only
Sample basis	Recent items per content type	All uploads in trailing 12-week window
Key fields	`avg_views`, `avg_likes`, `avg_comments`, `avg_engagement_rate`	`avg_duration_seconds`, `uploads_per_week`, `pct_over_8m`
Use case	Creator quality and audience responsiveness	Ad inventory estimation and upload consistency

Edge Cases

Null Fields

Any metric field can be null. Common causes:

Scenario	Result
Platform doesn’t support a metric (e.g., Twitch has no likes)	`avg_likes: null`
No content available for calculation	Entire metric object is omitted
Comments disabled on all sampled videos	`avg_comments: null` (excluded from engagement rate)
No uploads in the video metrics window	`avg_duration_seconds: null`, `pct_over_8m: null`

Engagement Rate Calculation

avg_engagement_rate requires:

avg_views > 0
At least one of avg_likes or avg_comments is non-null

If either condition isn’t met, avg_engagement_rate is null. When only one of likes/comments is available (e.g., Twitch), the missing value is treated as 0 in the numerator.

Data Freshness

Metrics are cached and refreshed periodically. If you need guaranteed fresh data for a specific creator, contact support.

API Reference

Agents + LLMs

Updates

Engagement Metrics

Fields

Platform Coverage

How Calculation Works

Example

Response Example

Video Metrics

Fields

Lookback Window

Coverage Metadata

Mid-Roll Eligibility

Response Examples

Engagement vs. Video Metrics

Edge Cases

Null Fields

Engagement Rate Calculation

Data Freshness

API Reference

Agents + LLMs

Updates

​Engagement Metrics

​Fields

​Platform Coverage

​How Calculation Works

​Example

​Response Example

​Video Metrics

​Fields

​Lookback Window

​Coverage Metadata

​Mid-Roll Eligibility

​Response Examples

​Engagement vs. Video Metrics

​Edge Cases

​Null Fields

​Engagement Rate Calculation

​Data Freshness

Engagement Metrics

Fields

Platform Coverage

How Calculation Works

Example

Response Example

Video Metrics

Fields

Lookback Window

Coverage Metadata

Mid-Roll Eligibility

Response Examples

Engagement vs. Video Metrics

Edge Cases

Null Fields

Engagement Rate Calculation

Data Freshness