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

# Data reference

> Metrics, breakdowns, refresh cadence, and limits for the Vimeo data source in Adriel.

## Introduction

Vimeo is a video hosting and publishing platform. In Adriel it is an organic video connector: it reads channel-level and video-level performance for the videos published on the connected Vimeo account, so they can be reported alongside other organic and paid sources.

Vimeo's API exposes only **lifetime (cumulative) totals** — a snapshot of each value at the moment it is read — with no endpoint for historical daily values ([Vimeo API reference](https://developer.vimeo.com/api/reference)). To build a daily time series, Adriel stores one lifetime snapshot per day and derives per-period **delta** metrics (day-over-day change) from consecutive snapshots. Both the lifetime and the delta form of each core metric are available in the field picker.

One data source is created per connected Vimeo account. Videos on that account are the reporting units at the video level, and the account itself is the reporting unit at the channel level. To connect this data source, see [How to connect Vimeo to Adriel](/data-sources/o-z/vimeo/how-to-connect).

## Data refresh strategy

### Architecture data

Architecture covers discovery of the connected Vimeo channel and its video catalog. Videos are listed from the account (`GET /me/videos`), paginated and sorted by most recent activity, and the per-video metadata (title, description, link, embed media, publish date) is cached. Newly published videos appear after the next daily refresh cycle.

### Reports data

Reports data is served from Adriel's daily cache rather than live per dashboard load, because Vimeo returns only lifetime snapshots:

* **Video (post) performance** — at connection, videos created within roughly the last 10 years are retrieved. Only lifetime metrics exist at that point; there are no historical daily values, so daily history accumulates from the connection date forward as each day's snapshot is stored. The video cache refreshes once daily.
* **Channel (page) data** — at connection, up to the last 90 days of daily channel rows are backfilled. On each refresh the most recent 3 days are re-fetched. Follower and audience figures have no historical backfill — only the daily snapshots captured since connection are retained.

<Note>
  **Lifetime totals vs per-period deltas**

  Every core Vimeo metric comes in two forms:

  * **Lifetime** — the cumulative total as of the latest snapshot (e.g. all plays a video has ever received).
  * **Delta** — the day-over-day change, derived by subtracting consecutive lifetime snapshots. Deltas are what power time-series charts.

  Because Vimeo provides no historical daily data, three consequences follow:

  * Daily history only begins accumulating on the **connection date**. Videos published before connection start with a delta of 0 on that first day.
  * For videos published before connection, the **sum of deltas will not equal the lifetime total**, since the pre-connection accumulation was never broken out by day.
  * If a daily snapshot is missing (for example, API downtime), the delta for that gap is **linearly estimated** from the last available data point.
</Note>

## Architecture levels

Account (channel) → Videos

A connected Vimeo account (read via `/me`) is the channel and the reporting boundary; each video published on that account is an individual reporting unit. Vimeo has no ad hierarchy.

## Date range limits

| Breakdown | Max range |
| --------- | --------- |
| Daily     | 93 days   |
| Weekly    | 1 year    |

Daily and weekly time groupings are capped as above; data outside the cap may be truncated. Monthly, quarterly, and yearly groupings have no separate cap. Overall, history is available for up to roughly 10 years (3650 days) back.

## Metrics

<Note>
  **How to read the columns**

  Code style like `videoPlays` is the literal field name exposed by the connector. *Italic text* describes how a value is produced when it is computed by Adriel rather than read directly from Vimeo.

  **Data type vocabulary**: Number, Currency, Percentage, Ratio, Duration, Date, Text, URL, Array, Boolean.
</Note>

<Note>
  **Lifetime and delta pairs**

  Most metrics below appear twice — once as a **lifetime** value (cumulative total from Vimeo) and once as a **delta** value (day-over-day change derived by Adriel from consecutive lifetime snapshots). See [Lifetime totals vs per-period deltas](#reports-data) above for why the two do not always reconcile.
</Note>

### Video performance

| Metric                 | Description                                                                      | Data type | API Key                                           |
| ---------------------- | -------------------------------------------------------------------------------- | --------- | ------------------------------------------------- |
| Video plays (lifetime) | Cumulative number of times the video has been played, as of the latest snapshot. | Number    | `videoPlays`                                      |
| Video plays (delta)    | Day-over-day change in plays.                                                    | Number    | *daily delta of `videoPlays`, computed by Adriel* |

<Note>
  Vimeo does not expose watch time, audience retention, or finish/quartile completion rates through the connector — video-level analytics of that kind require a higher-tier Vimeo plan and are not implemented ([Vimeo API reference](https://developer.vimeo.com/api/reference)). Only play counts are available at the video level.
</Note>

### Engagement

| Metric                    | Description                                  | Data type | API Key                                              |
| ------------------------- | -------------------------------------------- | --------- | ---------------------------------------------------- |
| Video likes (lifetime)    | Cumulative likes on the video.               | Number    | `videoLikes`                                         |
| Video likes (delta)       | Day-over-day change in likes.                | Number    | *daily delta of `videoLikes`, computed by Adriel*    |
| Video comments (lifetime) | Cumulative top-level comments on the video.  | Number    | `videoComments`                                      |
| Video comments (delta)    | Day-over-day change in comments.             | Number    | *daily delta of `videoComments`, computed by Adriel* |
| Video replies (lifetime)  | Cumulative replies to comments on the video. | Number    | `videoReplies`                                       |
| Video replies (delta)     | Day-over-day change in replies.              | Number    | *daily delta of `videoReplies`, computed by Adriel*  |

<Note>
  Vimeo returns a single combined comment count. Adriel splits it into comments and replies; the split is only refined with an extra request when a video has more than one comment, so channels with many commented videos take longer to refresh.
</Note>

### Channel & audience

| Metric                    | Description                                                          | Data type | API Key                                                          |
| ------------------------- | -------------------------------------------------------------------- | --------- | ---------------------------------------------------------------- |
| Followers (lifetime)      | Total followers of the connected channel, as of the latest snapshot. | Number    | `lifetimeFollowCount`                                            |
| Followers (delta)         | Day-over-day change in followers.                                    | Number    | *daily delta of `lifetimeFollowCount`, exposed as `followCount`* |
| Videos on channel         | Total number of videos on the connected channel.                     | Number    | `userVideoCount`                                                 |
| Videos on channel (delta) | Day-over-day change in the channel's video count.                    | Number    | *daily delta of `userVideoCount`, computed by Adriel*            |

### Video metadata

Descriptive fields attached to each video. They carry no numeric aggregation and are used to label and link video rows.

| Metric            | Description                                                                 | Data type | API Key            |
| ----------------- | --------------------------------------------------------------------------- | --------- | ------------------ |
| Video title       | Title (name) of the video.                                                  | Text      | `videoText`        |
| Video description | Description text of the video.                                              | Text      | `videoDescription` |
| Video date        | Publish date of the video (UTC when no timezone is set on the data source). | Date      | `videoDate`        |
| Video link        | Public URL of the video on Vimeo.                                           | URL       | `videoLink`        |
| Video media       | Player embed URL for the video (stored as an object with the embed link).   | URL       | `videoMedia`       |

## Breakdowns

<Note>
  **How to read the columns**

  Code style like `video` is the literal breakdown key exposed by the connector. *Italic text* describes a value produced by Adriel.
</Note>

### Channel

| Breakdown | Description                                                                | API Key |
| --------- | -------------------------------------------------------------------------- | ------- |
| Channel   | Groups results by the connected Vimeo channel (the authenticated account). | `user`  |

### Video

| Breakdown | Description                         | API Key |
| --------- | ----------------------------------- | ------- |
| Video     | Groups results by individual video. | `video` |

<Note>
  Channel (page-level) and video (post-level) breakdowns cannot be combined in the same query — video-level metrics must be viewed with the video breakdown, and channel-level metrics with the channel breakdown.
</Note>

### Time & date grouping

<Note>
  Adriel groups Vimeo's daily snapshots into these standard time views for reporting alongside other connectors.
</Note>

| Breakdown           | Description                                                  |
| ------------------- | ------------------------------------------------------------ |
| No grouping         | Return a single aggregated row for the whole date range.     |
| Auto Time Breakdown | Automatically picks the best granularity for the date range. |
| Daily               | Split reports by day (max range 93 days).                    |
| Weekly (Start: Mon) | Split reports by week starting Monday (max range 1 year).    |
| Monthly             | Split reports by calendar month.                             |
| Quarterly           | Split reports by calendar quarter.                           |
| Yearly              | Split reports by calendar year.                              |

## Limitations

Based on the current connector, Vimeo has:

* **Beta status** — the connector is surfaced in the app as "Vimeo (beta)"; some fields may still change.
* **Lifetime-only source data** — Vimeo returns only cumulative snapshots. Daily history accumulates from the connection date forward; there is no way to backfill daily values for periods before connection.
* **Deltas that don't reconcile with lifetime totals** — for videos published before connection, the sum of daily deltas will not match the lifetime total, and the first day's delta is 0.
* **Estimated deltas on gaps** — when a daily snapshot is missing, the delta for that gap is linearly estimated rather than measured.
* **No historical follower/audience data** — follower figures are only captured as daily snapshots from the connection date; there is no historical backfill.
* **No video-level watch time, retention, or completion metrics** — these require a higher-tier Vimeo plan and are not implemented; only play, like, comment, and reply counts are available per video.
* **A \~10-year lookback** — videos created more than about 10 years ago are excluded, and delta values for very old posts (3+ years) or posts no longer retrievable via the API (deleted or restricted) may not be recorded.
* **Media that can expire** — a video's associated media (embed/thumbnail URL) may stop resolving if the video is no longer accessible through the API.
* **No mixing of channel and video breakdowns** — combining page-level and post-level breakdowns in one query is rejected.
* **No automatic token refresh** — Vimeo access tokens are long-lived; if a token does expire, the data source must be reconnected manually.
* **One data source per connected Vimeo account.**

## API references

* [Vimeo API reference (v3.4)](https://developer.vimeo.com/api/reference)
* [Videos endpoint (`GET /me/videos`)](https://developer.vimeo.com/api/reference/videos)
* [Vimeo API authentication (OAuth 2.0)](https://developer.vimeo.com/api/authentication)

## See also

* [How to connect Vimeo](/data-sources/o-z/vimeo/how-to-connect) (paired how-to)
* [YouTube Analytics data reference](/data-sources/o-z/youtube-analytics/data-reference) — for the other organic video connector