Read YouTube connection status
/sites/{site_id}/youtube/connectionyoutube: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. No provider credentials are exposed. An authorized site with no YouTube connection returns status=not_connected. A company administrator connects/selects the channel in /youtube/.
| Request | GET https://satelliteai.io/api/v1/sites/{site_id}/youtube/connection |
| Permission | youtube:read |
| Response | A single object: data is YouTubeConnection. |
| Operation ID | getYouTubeConnection |
More context and worked examples are in the developer guide.
Example request
curl --fail-with-body \
'https://satelliteai.io/api/v1/sites/123/youtube/connection' \
-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 |
Unknown or repeated query parameters return 400.
Data dictionary
Connection state, including status=not_connected for an authorized site without a grant.
[] 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.site_id | integer | Satellite site ID (from GET /sites). |
data.status | string | one of: not_connected, connected_unselected, active, needs_reauth, revoking, disconnected |
data.channel_id | stringnullable | |
data.last_synced_at | stringnullable | UTC timestamp of last completed publication, 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 |
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. |