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

i

Info

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.

1. Fetch recent content

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

2. Average per content type

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

3. 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.

4. 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.

i

Note

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

i

Info

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.