> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upriver.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Metrics

> How engagement metrics and video metrics are calculated, which platforms they cover, and how to interpret them

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.

```bash theme={null}
# 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                     |

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

### How Calculation Works

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

<Steps>
  <Step title="Fetch recent content">
    Recent items are collected per content type — for example, YouTube Videos and Shorts are sampled separately.
  </Step>

  <Step title="Average per content type">
    Within each content type, metrics are averaged independently — average views, average likes, and average comments for that type alone.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

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

```json theme={null}
{
  "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.

<Note>
  Video metrics are currently available for **YouTube only**.
</Note>

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

<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.
</Info>

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

<AccordionGroup>
  <Accordion title="Established creator with consistent uploads">
    ```json theme={null}
    {
      "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.
  </Accordion>

  <Accordion title="New creator with limited history">
    ```json theme={null}
    {
      "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.
  </Accordion>

  <Accordion title="Inactive creator (no uploads in window)">
    ```json theme={null}
    {
      "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.
  </Accordion>
</AccordionGroup>

***

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