Returns a list of posts that match the API request parameters.
Users who own or manage a channel can retrieve all of the channel's posts, including scheduled and archived posts. Other users can retrieve only published public posts.
Quota impact: A call to this method has a quota cost of 1 unit. The cost counts against the Post List Queries quota, which is separate from the default YouTube Data API quota.
Request
HTTP request
GET https://www.googleapis.com/youtube/v3/posts
Authorization
Authorization is required to retrieve non-public posts, such as scheduled or archived posts for a channel that the user owns or manages, but isn't required to retrieve published public posts. If authorization is provided, the request must be authorized with at least one of the following scopes (read more about authentication and authorization).
| Scope |
|---|
https://www.googleapis.com/auth/youtube.readonly |
https://www.googleapis.com/auth/youtubepartner |
https://www.googleapis.com/auth/youtube |
https://www.googleapis.com/auth/youtube.force-ssl |
Parameters
The following table lists the parameters that this query supports. All of the parameters listed are query parameters.
| Parameters | |
|---|---|
| Required parameters | |
part |
stringThe part parameter specifies a comma-separated list of one or more post resource properties that the API response includes.The following list contains the part names that you can include in the parameter value:
|
| Filters (specify exactly one of the following parameters) | |
channelId |
stringThe channelId parameter instructs the API to return posts published by the specified channel. |
postId |
stringThe postId parameter specifies a comma-separated list of the YouTube post IDs for the resources that are being retrieved.The response omits posts that don't exist or that the caller can't view. |
| Optional parameters | |
maxResults |
unsigned integerThe maxResults parameter specifies the maximum number of items that should be returned in the result set. Acceptable values are 1 to 50, inclusive. The default value is 20.This parameter applies only when you use the channelId filter. |
pageToken |
stringThe pageToken parameter identifies a specific page in the result set that should be returned. In an API response, the nextPageToken property identifies the next page that can be retrieved.This parameter applies only when you use the channelId filter. |
Request body
Don't provide a request body when calling this method.
Response
If successful, this method returns a response body with the following structure:
{
"kind": "youtube#postListResponse",
"etag": etag,
"nextPageToken": string,
"items": [
post Resource
]
}Properties
The following table defines the properties that appear in this resource:
| Properties | |
|---|---|
kind |
stringIdentifies the API resource's type. The value is youtube#postListResponse. |
etag |
etagThe Etag of this resource. |
nextPageToken |
stringThe token that can be used as the value of the pageToken parameter to retrieve the next page in the result set. |
items[] |
listA list of posts that match the request criteria. If the channel has no posts that the authorized user can view, the list is empty. |
Errors
The following table identifies error messages that the API could return in response to a call to this method. For more detail, see the error message documentation.
| Error type | Error detail | Description |
|---|---|---|
invalidValue (400) |
invalidMetadata |
The request contains invalid metadata values. |
forbidden (403) |
forbidden |
The request is not properly authorized. |
rateLimitExceeded (403) |
rateLimitExceeded |
The request cannot be completed because you have exceeded your rate limit. |
notFound (404) |
channelNotFound |
The specified channel was not found. |