API reference / YouTube / Subscriptions list

Subscriptions list

Read-only YouTube Data API v3 subscriptions list endpoint.

1 credit per successful call Errors are never charged

Request

GET https://socialgraph.dev/api/v1/youtube/subscriptions

Send your API key as Authorization: Bearer YOUR_API_KEY. Parameters go in the query string.

Parameters

Name	Type	Description
`part` required	string	Required. Comma-separated: id, snippet or contentDetails. For example: snippet
`channelId` required	string	Required. Channel whose subscriptions to list. Only works if the channel keeps its subscriptions public; otherwise YouTube returns 403 subscriptionForbidden. For example: UCK8sQmJBp8GCxrOtXWBpyEA
`forChannelId` optional	string	Comma-separated channel IDs: only return subscriptions to these channels.
`order` optional	string	relevance (default), alphabetical or unread.
`maxResults` optional	integer	Maximum results per page (0–50). Default 5.
`pageToken` optional	string	Token from a previous response (nextPageToken or prevPageToken).

Code examples

Example response

{
    "etag": "j2lSBxD_gRDRR4KMbN_ZpTcQT7s",
    "kind": "youtube#SubscriptionListResponse",
    "items": [
        {
            "id": "X7RMFNKroIVZdx7dS5nlXp6hV54sZ1hPeUfuAelW9Os",
            "etag": "CstZRqv8LPTOpgNSQlYsxv8g9CE",
            "kind": "youtube#subscription",
            "snippet": {
                "title": "Google Pay",
                "channelId": "UCK8sQmJBp8GCxrOtXWBpyEA",
                "resourceId": {
                    "kind": "youtube#channel",
                    "channelId": "UC-kIUbVyk6WOBN5z0hGThMQ"
                },
                "thumbnails": {
                    "high": {
                        "url": "https://yt3.ggpht.com/6rMdGM9s3TsCJZiLibu4v4fhG3yIDPHVbsZuS1lJZ88EcBkZJ61SjXqCy_wycznHMyJRnE0E=s800-c-k-c0x00ffffff-no-rj"
                    },
                    "medium": {
                        "url": "https://yt3.ggpht.com/6rMdGM9s3TsCJZiLibu4v4fhG3yIDPHVbsZuS1lJZ88EcBkZJ61SjXqCy_wycznHMyJRnE0E=s240-c-k-c0x00ffffff-no-rj"
                    },
                    "default": {
                        "url": "https://yt3.ggpht.com/6rMdGM9s3TsCJZiLibu4v4fhG3yIDPHVbsZuS1lJZ88EcBkZJ61SjXqCy_wycznHMyJRnE0E=s88-c-k-c0x00ffffff-no-rj"
                    }
                },
                "description": "",
                "publishedAt": "2020-06-16T18:05:27.788955Z"
            }
        },
        {
            "id": "X7RMFNKroIVT2j3zlJcZK0AkLKGorcsp8Lnu0VP_85s",
            "etag": "znap7CacHjEZIZn0dH1lSMLA0aU",
            "kind": "youtube#subscription",
            "snippet": {
                "title": "Google Help",
                "channelId": "UCK8sQmJBp8GCxrOtXWBpyEA",
                "resourceId": {
                    "kind": "youtube#channel",
                    "channelId": "UC3x6qC4h-NyuvQBSZYaPKrQ"
                },
                "thumbnails": {
                    "high": {
                        "url": "https://yt3.ggpht.com/p_5CCE_zV7V47pu55FvaQrXid6lg-XAVqMQUGtLjSI24PUbKRFY1EvYimUwQ0SzvfV83TUO6pJc=s800-c-k-c0x00ffffff-no-rj"
                    },
                    "medium": {
                        "url": "https://yt3.ggpht.com/p_5CCE_zV7V47pu55FvaQrXid6lg-XAVqMQUGtLjSI24PUbKRFY1EvYimUwQ0SzvfV83TUO6pJc=s240-c-k-c0x00ffffff-no-rj"
                    },
                    "default": {
                        "url": "https://yt3.ggpht.com/p_5CCE_zV7V47pu55FvaQrXid6lg-XAVqMQUGtLjSI24PUbKRFY1EvYimUwQ0SzvfV83TUO6pJc=s88-c-k-c0x00ffffff-no-rj"
                    }
                },
                "description": "Welcome to the official Google Help YouTube channel. Learn to use Google products with how-to videos and tips & tricks. Whether you're new to Google or a seasoned pro, we've got you covered. Subscribe to the channel to stay up-to-date with the latest tutorials so you can get the most out of Google.",
                "publishedAt": "2025-02-06T16:05:59.634044Z"
            }
        },
        {
            "id": "X7RMFNKroIVT2j3zlJcZK4YW__Hj8daKAdWFcCHyMjQ",
            "etag": "OSoBTVrsWEf-4l5RixgxkdckeNc",
            "kind": "youtube#subscription",
            "snippet": {
                "title": "Google France",
                "channelId": "UCK8sQmJBp8GCxrOtXWBpyEA",
                "resourceId": {
                    "kind": "youtube#channel",
                    "channelId": "UC6KUvtitNkyAZdJpR03DAHg"
                },
                "thumbnails": {
                    "high": {
                        "url": "https://yt3.ggpht.com/GIs0GQ1LNQRnNHe1C53Awl2P4GTG57LMMa-fEkt8NJebXrZX-0ang3zQXjKLllX2CyGfkw76Qhw=s800-c-k-c0x00ffffff-no-rj"
                    },
                    "medium": {
                        "url": "https://yt3.ggpht.com/GIs0GQ1LNQRnNHe1C53Awl2P4GTG57LMMa-fEkt8NJebXrZX-0ang3zQXjKLllX2CyGfkw76Qhw=s240-c-k-c0x00ffffff-no-rj"
                    },
                    "default": {
                        "url": "https://yt3.ggpht.com/GIs0GQ1LNQRnNHe1C53Awl2P4GTG57LMMa-fEkt8NJebXrZX-0ang3zQXjKLllX2CyGfkw76Qhw=s88-c-k-c0x00ffffff-no-rj"
                    }
                },
                "description": "La chaîne officielle de Google France ✨",
                "publishedAt": "2008-07-23T04:52:27Z"
            }
        },
        {
            "id": "X7RMFNKroIVT2j3zlJcZK5wY_Idc3BG3RSymmkbXtM4",
            "etag": "R32x2eySc0XEnjf8pAk3COqvaEE",
            "kind": "youtube#subscription",
            "snippet": {
                "title": "Android",
                "channelId": "UCK8sQmJBp8GCxrOtXWBpyEA",
                "resourceId": {
                    "kind": "youtube#channel",
                    "channelId": "UC9M7-jzdU8CVrQo1JwmIdWA"
                },
                "thumbnails": {
                    "high": {
                        "url": "https://yt3.ggpht.com/M31l5D8Utnqy1VpnSotUmBoOBOLbRSG6m9QIufGgflb9o4xtwJgVS5ORYso5uS2O4Gyc-t6TzHQ=s800-c-k-c0x00ffffff-no-rj"
                    },
                    "medium": {
                        "url": "https://yt3.ggpht.com/M31l5D8Utnqy1VpnSotUmBoOBOLbRSG6m9QIufGgflb9o4xtwJgVS5ORYso5uS2O4Gyc-t6TzHQ=s240-c-k-c0x00ffffff-no-rj"
                    },
                    "default": {
                        "url": "https://yt3.ggpht.com/M31l5D8Utnqy1VpnSotUmBoOBOLbRSG6m9QIufGgflb9o4xtwJgVS5ORYso5uS2O4Gyc-t6TzHQ=s88-c-k-c0x00ffffff-no-rj"
                    }
                },
                "description": "Android is for everyone",
                "publishedAt": "2015-03-30T17:35:48Z"
            }
        },
        {
            "id": "X7RMFNKroIVT2j3zlJcZK0xPbQ3GJjA1_XzMcaIZ5I0",
            "etag": "aTfbODvGWIf3q9Y1-ArYNq05tow",
            "kind": "youtube#subscription",
            "snippet": {
                "title": "YouTube",
                "channelId": "UCK8sQmJBp8GCxrOtXWBpyEA",
                "resourceId": {
                    "kind": "youtube#channel",
                    "channelId": "UCBR8-60-B28hp2BmDPdntcQ"
                },
                "thumbnails": {
                    "high": {
                        "url": "https://yt3.ggpht.com/3s6evpqAiDU9tQR4sC2siJippbH2RWVPnwHgyl4V0th2iuQz0VDQZbUhQBGmsxLYo-mjG6TqZQ=s800-c-k-c0x00ffffff-no-rj"
                    },
                    "medium": {
                        "url": "https://yt3.ggpht.com/3s6evpqAiDU9tQR4sC2siJippbH2RWVPnwHgyl4V0th2iuQz0VDQZbUhQBGmsxLYo-mjG6TqZQ=s240-c-k-c0x00ffffff-no-rj"
                    },
                    "default": {
                        "url": "https://yt3.ggpht.com/3s6evpqAiDU9tQR4sC2siJippbH2RWVPnwHgyl4V0th2iuQz0VDQZbUhQBGmsxLYo-mjG6TqZQ=s88-c-k-c0x00ffffff-no-rj"
                    }
                },
                "description": "YouTube's official YouTube channel",
                "publishedAt": "2010-03-30T18:47:11Z"
            }
        }
    ],
    "pageInfo": {
        "totalResults": 36,
        "resultsPerPage": 5
    },
    "nextPageToken": "CAUQAA"
}

Errors

Status	Meaning	Charged?
401	Missing, invalid or revoked API key	No
402	Not enough credits (`insufficient_credits`)	No
404	The account or post doesn't exist	No
422	Missing or invalid parameters	No
502 / 503	The data source is temporarily unavailable	No

All error codes →

Try it live: Subscriptions list GET

part

channelId

maxResults

🔒 Preset demo input. Live demos use the Google for Developers channel, youtube.com/@GoogleDevelopers. Sign up free to use your own.

More YouTube endpoints

GET Activities list Read-only YouTube Data API v3 activities list endpoint. /api/v1/youtube/activities 1 credit / call GET Channel sections list Read-only YouTube Data API v3 channelSections list endpoint. /api/v1/youtube/channelSections 1 credit / call GET Channels list Read-only YouTube Data API v3 channels list endpoint. /api/v1/youtube/channels 1 credit / call GET Comment threads list Read-only YouTube Data API v3 commentThreads list endpoint. /api/v1/youtube/commentThreads 1 credit / call GET Comments list Read-only YouTube Data API v3 comments list endpoint. /api/v1/youtube/comments 1 credit / call GET Internationalization languages list Read-only YouTube Data API v3 i18nLanguages list endpoint. /api/v1/youtube/i18nLanguages 1 credit / call