Posts: list

This method is in a pilot phase with access limited to select launch partners (approved Google Cloud projects). Broader public API access is planned for General Availability in 2027.

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 string
The 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:
  • attachments
  • id
  • snippet
  • statistics
  • status
Filters (specify exactly one of the following parameters)
channelId string
The channelId parameter instructs the API to return posts published by the specified channel.
postId string
The 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 integer
The 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 string
The 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 string
Identifies the API resource's type. The value is youtube#postListResponse.
etag etag
The Etag of this resource.
nextPageToken string
The token that can be used as the value of the pageToken parameter to retrieve the next page in the result set.
items[] list
A 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.