Read an exact-range YouTube report

GET/sites/{site_id}/youtube/reportsyoutube:read

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

RequestGET https://satelliteai.io/api/v1/sites/{site_id}/youtube/reports
Permissionyoutube:read
ResponseA single object: data is YouTubeReport, or null when nothing is stored.
Operation IDgetYouTubeReport

More context and worked examples are in the developer guide.

Example request

cURL · Bash
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

NameInTypeDescription
site_idrequiredpathinteger
start_datequerystring (date)Inclusive Pacific start date. Defaults to 27 days before end_date (28 inclusive dates).
end_datequerystring (date)Inclusive Pacific end date. Defaults to yesterday. Must be before today; maximum 366 inclusive dates.
sourcequerystring
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.

Fields in data
FieldTypeDescription
data.start_datestring (date)Requested inclusive Pacific start date.
data.end_datestring (date)Requested inclusive Pacific end date.
data.data_throughstring (date)nullableLatest returned daily metric date. May precede end_date due to provider processing or sparse rows.
data.fetched_atstringUTC collection start timestamp, ISO8601 without timezone suffix.
data.timezonestring
one of: America/Los_Angeles
data.channelobject
data.channel.idstringAuthorized YouTube channel ID.
data.channel.titlestring
data.summaryobjectnullableYouTube aggregate for start_date through data_through; null when no daily rows were returned.
data.summary.viewsinteger (int64)nullableVideo views; not impressions.
data.summary.engagedViewsinteger (int64)nullableEngaged views reported by YouTube.
data.summary.estimatedMinutesWatchedinteger (int64)nullableEstimated watch time in minutes; divide by 60 for hours.
data.summary.averageViewDurationnumbernullableAverage viewing duration in seconds, supplied by YouTube; do not average daily averages.
data.summary.likesinteger (int64)nullableLikes reported for the period.
data.summary.commentsinteger (int64)nullableComments reported for the period.
data.summary.sharesinteger (int64)nullableShares reported for the period.
data.summary.subscribersGainedinteger (int64)nullableSubscribers gained during the period.
data.summary.subscribersLostinteger (int64)nullableSubscribers lost during the period.
data.dailyarray of YouTubeDailyRow
max items 366
data.daily[].viewsinteger (int64)nullableVideo views; not impressions.
data.daily[].engagedViewsinteger (int64)nullableEngaged views reported by YouTube.
data.daily[].estimatedMinutesWatchedinteger (int64)nullableEstimated watch time in minutes; divide by 60 for hours.
data.daily[].averageViewDurationnumbernullableAverage viewing duration in seconds, supplied by YouTube; do not average daily averages.
data.daily[].likesinteger (int64)nullableLikes reported for the period.
data.daily[].commentsinteger (int64)nullableComments reported for the period.
data.daily[].sharesinteger (int64)nullableShares reported for the period.
data.daily[].subscribersGainedinteger (int64)nullableSubscribers gained during the period.
data.daily[].subscribersLostinteger (int64)nullableSubscribers lost during the period.
data.daily[].daystringPacific date, YYYY-MM-DD. Missing dates are omitted, not fabricated as zero.
data.videosarray of YouTubeVideoRow
max items 200
data.videos[].viewsinteger (int64)nullableVideo views; not impressions.
data.videos[].engagedViewsinteger (int64)nullableEngaged views reported by YouTube.
data.videos[].estimatedMinutesWatchedinteger (int64)nullableEstimated watch time in minutes; divide by 60 for hours.
data.videos[].averageViewDurationnumbernullableAverage viewing duration in seconds, supplied by YouTube; do not average daily averages.
data.videos[].likesinteger (int64)nullableLikes reported for the period.
data.videos[].commentsinteger (int64)nullableComments reported for the period.
data.videos[].sharesinteger (int64)nullableShares reported for the period.
data.videos[].subscribersGainedinteger (int64)nullableSubscribers gained during the period.
data.videos[].subscribersLostinteger (int64)nullableSubscribers lost during the period.
data.videos[].videostringYouTube video ID, not a Satellite page ID.
data.videos[].titlestringPresent when YouTube metadata provides a title; use the video ID otherwise.
data.countriesarray of YouTubeCountryRow
data.countries[].viewsinteger (int64)nullableVideo views; not impressions.
data.countries[].estimatedMinutesWatchedinteger (int64)nullableEstimated watch time in minutes; divide by 60 for hours.
data.countries[].countrystringYouTube country code. Privacy limits may omit activity.
data.trafficarray of YouTubeTrafficRow
data.traffic[].viewsinteger (int64)nullableVideo views; not impressions.
data.traffic[].estimatedMinutesWatchedinteger (int64)nullableEstimated watch time in minutes; divide by 60 for hours.
data.traffic[].insightTrafficSourceTypestringYouTube traffic-source code, for example YT_SEARCH or EXT_URL.
data.video_limitinteger
one of: 200
data.coverageobjectOne completed state per collected dataset. This is not a guarantee of complete provider attribution.
data.coverage.dailyobject
data.coverage.daily.statusstringobserved_empty is a completed provider dataset with no rows.
one of: ready, observed_empty
data.coverage.daily.row_countinteger
data.coverage.daily.fetched_atstringUTC collection timestamp; ISO8601 without timezone suffix.
data.coverage.summaryobject
data.coverage.summary.statusstringobserved_empty is a completed provider dataset with no rows.
one of: ready, observed_empty
data.coverage.summary.row_countinteger
data.coverage.summary.fetched_atstringUTC collection timestamp; ISO8601 without timezone suffix.
data.coverage.videosobject
data.coverage.videos.statusstringobserved_empty is a completed provider dataset with no rows.
one of: ready, observed_empty
data.coverage.videos.row_countinteger
data.coverage.videos.fetched_atstringUTC collection timestamp; ISO8601 without timezone suffix.
data.coverage.countriesobject
data.coverage.countries.statusstringobserved_empty is a completed provider dataset with no rows.
one of: ready, observed_empty
data.coverage.countries.row_countinteger
data.coverage.countries.fetched_atstringUTC collection timestamp; ISO8601 without timezone suffix.
data.coverage.trafficobject
data.coverage.traffic.statusstringobserved_empty is a completed provider dataset with no rows.
one of: ready, observed_empty
data.coverage.traffic.row_countinteger
data.coverage.traffic.fetched_atstringUTC collection timestamp; ISO8601 without timezone suffix.
data.coverage.metadataobject
data.coverage.metadata.statusstringobserved_empty is a completed provider dataset with no rows.
one of: ready, observed_empty
data.coverage.metadata.row_countinteger
data.coverage.metadata.fetched_atstringUTC collection timestamp; ISO8601 without timezone suffix.

Response metadata

Fields in meta
FieldTypeDescription
meta.sourcestring
one of: stored
meta.request_idstringRequest identifier; also returned in X-Request-ID. Include it in support requests.
meta.api_versionstringAPI version that produced the response.
one of: v1
meta.availabilitystringavailable when stored data exists; not_available when it does not.
one of: available, not_available
meta.start_datestring (date)
meta.end_datestring (date)

Error responses

Errors return {"error": {"code", "message", "request_id"}}. See error handling for retry guidance.

HTTPWhen
400Invalid dates or unsupported source
403Missing youtube:read, disabled integration, or company API access disabled.
404Site not found or not granted
401Missing, invalid, expired or revoked Bearer API key.
429Rate limit reached; respect Retry-After.