Read an exact-range YouTube report
/sites/{site_id}/youtube/reportsyoutube:readRequires youtube:read and an explicit site grant. Uses the same canonical normalized-data reader as the dashboard. Reads never contact Google, refresh tokens, queue collection, or deduct Satellite credits. Dates match a complete stored report exactly. Omit both dates for the last 28 Pacific dates through yesterday. Up to 366 inclusive dates, ending before today. Missing or disconnected reports return HTTP200 with data=null and meta.availability=not_available. The dashboard presets can show an older complete period; this API never silently substitutes dates. A site administrator connects/selects a channel and refreshes the desired period in /youtube/. source=live and period are unsupported.
| Request | GET https://satelliteai.io/api/v1/sites/{site_id}/youtube/reports |
| Permission | youtube:read |
| Response | A single object: data is YouTubeReport, or null when nothing is stored. |
| Operation ID | getYouTubeReport |
More context and worked examples are in the developer guide.
Example request
curl --fail-with-body \
'https://satelliteai.io/api/v1/sites/123/youtube/reports' \
-H "Authorization: Bearer $SATELLITE_API_KEY"Replace the example IDs with values returned by the discovery endpoints. Example values are placeholders, not real records.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
site_idrequired | path | integer | |
start_date | query | string (date) | Inclusive Pacific start date. Defaults to 27 days before end_date (28 inclusive dates). |
end_date | query | string (date) | Inclusive Pacific end date. Defaults to yesterday. Must be before today; maximum 366 inclusive dates. |
source | query | string | one of: stored · default stored |
Unknown or repeated query parameters return 400.
Data dictionary
Exact stored report or data=null when unavailable. Published exact-range report from normalized facts. Missing collection returns null; a collected empty period is an object with summary=null and observed_empty coverage. Top videos are capped at 200. Breakdowns end at data_through.
[] marks an array element. nullable means the value can be null; treat it as unknown, not zero. always present means the key is always included in the object.
| Field | Type | Description |
|---|---|---|
data.start_date | string (date) | Requested inclusive Pacific start date. |
data.end_date | string (date) | Requested inclusive Pacific end date. |
data.data_through | string (date)nullable | Latest returned daily metric date. May precede end_date due to provider processing or sparse rows. |
data.fetched_at | string | UTC collection start timestamp, ISO8601 without timezone suffix. |
data.timezone | string | one of: America/Los_Angeles |
data.channel | object | |
data.channel.id | string | Authorized YouTube channel ID. |
data.channel.title | string | |
data.summary | objectnullable | YouTube aggregate for start_date through data_through; null when no daily rows were returned. |
data.summary.views | integer (int64)nullable | Video views; not impressions. |
data.summary.engagedViews | integer (int64)nullable | Engaged views reported by YouTube. |
data.summary.estimatedMinutesWatched | integer (int64)nullable | Estimated watch time in minutes; divide by 60 for hours. |
data.summary.averageViewDuration | numbernullable | Average viewing duration in seconds, supplied by YouTube; do not average daily averages. |
data.summary.likes | integer (int64)nullable | Likes reported for the period. |
data.summary.comments | integer (int64)nullable | Comments reported for the period. |
data.summary.shares | integer (int64)nullable | Shares reported for the period. |
data.summary.subscribersGained | integer (int64)nullable | Subscribers gained during the period. |
data.summary.subscribersLost | integer (int64)nullable | Subscribers lost during the period. |
data.daily | array of YouTubeDailyRow | max items 366 |
data.daily[].views | integer (int64)nullable | Video views; not impressions. |
data.daily[].engagedViews | integer (int64)nullable | Engaged views reported by YouTube. |
data.daily[].estimatedMinutesWatched | integer (int64)nullable | Estimated watch time in minutes; divide by 60 for hours. |
data.daily[].averageViewDuration | numbernullable | Average viewing duration in seconds, supplied by YouTube; do not average daily averages. |
data.daily[].likes | integer (int64)nullable | Likes reported for the period. |
data.daily[].comments | integer (int64)nullable | Comments reported for the period. |
data.daily[].shares | integer (int64)nullable | Shares reported for the period. |
data.daily[].subscribersGained | integer (int64)nullable | Subscribers gained during the period. |
data.daily[].subscribersLost | integer (int64)nullable | Subscribers lost during the period. |
data.daily[].day | string | Pacific date, YYYY-MM-DD. Missing dates are omitted, not fabricated as zero. |
data.videos | array of YouTubeVideoRow | max items 200 |
data.videos[].views | integer (int64)nullable | Video views; not impressions. |
data.videos[].engagedViews | integer (int64)nullable | Engaged views reported by YouTube. |
data.videos[].estimatedMinutesWatched | integer (int64)nullable | Estimated watch time in minutes; divide by 60 for hours. |
data.videos[].averageViewDuration | numbernullable | Average viewing duration in seconds, supplied by YouTube; do not average daily averages. |
data.videos[].likes | integer (int64)nullable | Likes reported for the period. |
data.videos[].comments | integer (int64)nullable | Comments reported for the period. |
data.videos[].shares | integer (int64)nullable | Shares reported for the period. |
data.videos[].subscribersGained | integer (int64)nullable | Subscribers gained during the period. |
data.videos[].subscribersLost | integer (int64)nullable | Subscribers lost during the period. |
data.videos[].video | string | YouTube video ID, not a Satellite page ID. |
data.videos[].title | string | Present when YouTube metadata provides a title; use the video ID otherwise. |
data.countries | array of YouTubeCountryRow | |
data.countries[].views | integer (int64)nullable | Video views; not impressions. |
data.countries[].estimatedMinutesWatched | integer (int64)nullable | Estimated watch time in minutes; divide by 60 for hours. |
data.countries[].country | string | YouTube country code. Privacy limits may omit activity. |
data.traffic | array of YouTubeTrafficRow | |
data.traffic[].views | integer (int64)nullable | Video views; not impressions. |
data.traffic[].estimatedMinutesWatched | integer (int64)nullable | Estimated watch time in minutes; divide by 60 for hours. |
data.traffic[].insightTrafficSourceType | string | YouTube traffic-source code, for example YT_SEARCH or EXT_URL. |
data.video_limit | integer | one of: 200 |
data.coverage | object | One completed state per collected dataset. This is not a guarantee of complete provider attribution. |
data.coverage.daily | object | |
data.coverage.daily.status | string | observed_empty is a completed provider dataset with no rows. one of: ready, observed_empty |
data.coverage.daily.row_count | integer | |
data.coverage.daily.fetched_at | string | UTC collection timestamp; ISO8601 without timezone suffix. |
data.coverage.summary | object | |
data.coverage.summary.status | string | observed_empty is a completed provider dataset with no rows. one of: ready, observed_empty |
data.coverage.summary.row_count | integer | |
data.coverage.summary.fetched_at | string | UTC collection timestamp; ISO8601 without timezone suffix. |
data.coverage.videos | object | |
data.coverage.videos.status | string | observed_empty is a completed provider dataset with no rows. one of: ready, observed_empty |
data.coverage.videos.row_count | integer | |
data.coverage.videos.fetched_at | string | UTC collection timestamp; ISO8601 without timezone suffix. |
data.coverage.countries | object | |
data.coverage.countries.status | string | observed_empty is a completed provider dataset with no rows. one of: ready, observed_empty |
data.coverage.countries.row_count | integer | |
data.coverage.countries.fetched_at | string | UTC collection timestamp; ISO8601 without timezone suffix. |
data.coverage.traffic | object | |
data.coverage.traffic.status | string | observed_empty is a completed provider dataset with no rows. one of: ready, observed_empty |
data.coverage.traffic.row_count | integer | |
data.coverage.traffic.fetched_at | string | UTC collection timestamp; ISO8601 without timezone suffix. |
data.coverage.metadata | object | |
data.coverage.metadata.status | string | observed_empty is a completed provider dataset with no rows. one of: ready, observed_empty |
data.coverage.metadata.row_count | integer | |
data.coverage.metadata.fetched_at | string | UTC collection timestamp; ISO8601 without timezone suffix. |
Response metadata
| Field | Type | Description |
|---|---|---|
meta.source | string | one of: stored |
meta.request_id | string | Request identifier; also returned in X-Request-ID. Include it in support requests. |
meta.api_version | string | API version that produced the response. one of: v1 |
meta.availability | string | available when stored data exists; not_available when it does not. one of: available, not_available |
meta.start_date | string (date) | |
meta.end_date | string (date) |
Error responses
Errors return {"error": {"code", "message", "request_id"}}. See error handling for retry guidance.
| HTTP | When |
|---|---|
400 | Invalid dates or unsupported source |
403 | Missing youtube:read, disabled integration, or company API access disabled. |
404 | Site not found or not granted |
401 | Missing, invalid, expired or revoked Bearer API key. |
429 | Rate limit reached; respect Retry-After. |