Method: assetSearch.list
Stay organized with collections
Save and categorize content based on your preferences.
Searches for assets based on asset metadata. The method can retrieve all assets or only assets owned by the content owner. This method mimics the functionality of the advanced search feature on the Assets
page in CMS.
HTTP request
GET https://youtubepartner.googleapis.com/youtube/partner/v1/assetSearch
The URL uses gRPC Transcoding
syntax.
Query parameters
| Parameters |
createdAfter
|
string
The createdAfter
parameter restricts the set of returned assets to ones originally created on or after the specified datetime. For example: 2015-01-29T23:00:00Z
|
createdBefore
|
string
The createdBefore
parameter restricts the set of returned assets to ones originally created on or before the specified datetime. For example: 2015-01-29T23:00:00Z
|
hasConflicts
|
boolean
The hasConflicts
parameter enables you to only retrieve assets that have ownership conflicts. The only valid value is true
. Setting the parameter value to false
does not affect the results.
|
includeAnyProvidedlabel
|
boolean
If includeAnyProvidedlabel
parameter is set to true, will search for assets that contain any of the provided labels; else will search for assets that contain all the provided labels.
|
isrcs
|
string
A comma-separated list of up to 50 ISRCs. If you specify a value for this parameter, the API server ignores any values set for the following parameters: q
, includeAnyProvidedLabel
, hasConflicts
, labels
, metadataSearchFields
, sort
, and type
.
|
labels
|
string
The labels
parameter specifies the assets with certain asset labels that you want to retrieve. The parameter value is a comma-separated list of asset labels.
|
metadataSearchFields
|
string
The metadataSearchField
parameter specifies which metadata fields to search by. It is a comma-separated list of metadata field and value pairs connected by colon(:). For example: customId:my_custom_id,artist:Dandexx
|
onBehalfOfContentOwner
|
string
The onBehalfOfContentOwner
parameter identifies the content owner that the user is acting on behalf of. This parameter supports users whose accounts are associated with multiple content owners.
|
ownershipRestriction
|
enum ( OwnershipRestriction
)
The ownershipRestriction
parameter specifies the ownership filtering option for the search. By default the search is performed in the assets owned by currently authenticated user only.
|
pageToken
|
string
The pageToken
parameter specifies a token that identifies a particular page of results to return. Set this parameter to the value of the nextPageToken
value from the previous API response to retrieve the next page of search results.
|
q
|
string
YouTube searches within the id
, type
, and customId
fields for all assets as well as in numerous other metadata fields – such as actor
, album
, director
, isrc
, and tmsId
– that vary for different types of assets (movies, music videos, etc.).
|
sort
|
enum ( Sort
)
The sort
parameter specifies how the search results should be sorted. Note that results are always sorted in descending order.
|
type
|
string
The type
parameter specifies the types of assets that you want to retrieve. The parameter value is a comma-separated list of asset types.
|
Request body
The request body must be empty.
Response body
This response shows a list of YouTube assets matching a search query. Each item in the list contains an asset's metadata.
If successful, the response body contains data with the following structure:
| Fields |
kind
|
string
The type of the API response. For this operation, the value is youtubePartner#assetSnippetList
.
|
pageInfo
|
object ( PageInfo
)
The pageInfo
object encapsulates paging information for the result set.
|
items[]
|
object ( AssetSnippet
)
A list of asset resources that match the request criteria.
|
nextPageToken
|
string
The token that can be used as the value of the pageToken
parameter to retrieve the next page of results.
|
Authorization scopes
Requires the following OAuth scope:
-
https://www.googleapis.com/auth/youtubepartner
For more information, see the OAuth 2.0 Overview
.
OwnershipRestriction
Enum of ownership restriction.
Sort
Enum of supported sorting orders in asset search list request.
All rights reserved. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-08-20 UTC.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-20 UTC."],[[["\u003cp\u003eSearches YouTube assets based on metadata, like title, artist, or custom ID, and allows filtering by ownership, creation date, and more.\u003c/p\u003e\n"],["\u003cp\u003eThe search can be further refined using specific criteria such as ISRCs or labels to narrow down the results.\u003c/p\u003e\n"],["\u003cp\u003eResults are presented in pages, with options to sort by views, claims, or modification time and navigate through pages using tokens.\u003c/p\u003e\n"],["\u003cp\u003eAuthorization with the \u003ccode\u003eyoutubepartner\u003c/code\u003e scope is required to access this functionality.\u003c/p\u003e\n"]]],["This document outlines how to search for assets using the YouTube Partner API's `assetSearch` method. Key actions include sending a `GET` HTTP request to the specified URL, optionally including query parameters to filter results by creation date, conflicts, labels, ISRCs, metadata fields, and ownership. Sorting options (claims, time, views) are available. The response returns a list of assets, pagination details, and metadata. Authorization requires the `youtubepartner` scope. The request body should be empty.\n"],null,["# Method: assetSearch.list\n\n- [HTTP request](#body.HTTP_TEMPLATE)\n- [Query parameters](#body.QUERY_PARAMETERS)\n- [Request body](#body.request_body)\n- [Response body](#body.response_body)\n - [JSON representation](#body.AssetSearchResponse.SCHEMA_REPRESENTATION)\n- [Authorization scopes](#body.aspect)\n- [OwnershipRestriction](#OwnershipRestriction)\n- [Sort](#Sort)\n- [Try it!](#try-it)\n\nSearches for assets based on asset metadata. The method can retrieve all assets or only assets owned by the content owner. This method mimics the functionality of the advanced search feature on the [Assets](https://cms.youtube.com/assets) page in CMS.\n\n### HTTP request\n\n`GET https://youtubepartner.googleapis.com/youtube/partner/v1/assetSearch`\n\nThe URL uses [gRPC Transcoding](https://google.aip.dev/127) syntax.\n\n### Query parameters\n\n| Parameters ||\n|---------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `createdAfter` | `string` The `createdAfter` parameter restricts the set of returned assets to ones originally created on or after the specified datetime. For example: `2015-01-29T23:00:00Z` |\n| `createdBefore` | `string` The `createdBefore` parameter restricts the set of returned assets to ones originally created on or before the specified datetime. For example: `2015-01-29T23:00:00Z` |\n| `hasConflicts` | `boolean` The `hasConflicts` parameter enables you to only retrieve assets that have ownership conflicts. The only valid value is `true`. Setting the parameter value to `false` does not affect the results. |\n| `includeAnyProvidedlabel` | `boolean` If `includeAnyProvidedlabel` parameter is set to true, will search for assets that contain any of the provided labels; else will search for assets that contain all the provided labels. |\n| `isrcs` | `string` A comma-separated list of up to 50 ISRCs. If you specify a value for this parameter, the API server ignores any values set for the following parameters: `q`, `includeAnyProvidedLabel`, `hasConflicts`, `labels`, `metadataSearchFields`, `sort`, and `type`. |\n| `labels` | `string` The `labels` parameter specifies the assets with certain asset labels that you want to retrieve. The parameter value is a comma-separated list of asset labels. |\n| `metadataSearchFields` | `string` The `metadataSearchField` parameter specifies which metadata fields to search by. It is a comma-separated list of metadata field and value pairs connected by colon(:). For example: customId:my_custom_id,artist:Dandexx |\n| `onBehalfOfContentOwner` | `string` The `onBehalfOfContentOwner` parameter identifies the content owner that the user is acting on behalf of. This parameter supports users whose accounts are associated with multiple content owners. |\n| `ownershipRestriction` | `enum (`[OwnershipRestriction](/youtube/partner/reference/rest/v1/assetSearch/list#OwnershipRestriction)`)` The `ownershipRestriction` parameter specifies the ownership filtering option for the search. By default the search is performed in the assets owned by currently authenticated user only. |\n| `pageToken` | `string` The `pageToken` parameter specifies a token that identifies a particular page of results to return. Set this parameter to the value of the `nextPageToken` value from the previous API response to retrieve the next page of search results. |\n| `q` | `string` YouTube searches within the `id`, `type`, and `customId` fields for all assets as well as in numerous other metadata fields -- such as `actor`, `album`, `director`, `isrc`, and `tmsId` -- that vary for different types of assets (movies, music videos, etc.). |\n| `sort` | `enum (`[Sort](/youtube/partner/reference/rest/v1/assetSearch/list#Sort)`)` The `sort` parameter specifies how the search results should be sorted. Note that results are always sorted in descending order. |\n| `type` | `string` The `type` parameter specifies the types of assets that you want to retrieve. The parameter value is a comma-separated list of asset types. |\n\n### Request body\n\nThe request body must be empty.\n\n### Response body\n\nThis response shows a list of YouTube assets matching a search query. Each item in the list contains an asset's metadata.\n\nIf successful, the response body contains data with the following structure:\n\n| JSON representation |\n|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| ``` { \"kind\": string, \"pageInfo\": { object (/youtube/partner/reference/rest/v1/PageInfo) }, \"items\": [ { object (/youtube/partner/reference/rest/v1/assetSearch#AssetSnippet) } ], \"nextPageToken\": string } ``` |\n\n| Fields ||\n|-----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------|\n| `kind` | `string` The type of the API response. For this operation, the value is `youtubePartner#assetSnippetList`. |\n| `pageInfo` | `object (`[PageInfo](/youtube/partner/reference/rest/v1/PageInfo)`)` The `pageInfo` object encapsulates paging information for the result set. |\n| `items[]` | `object (`[AssetSnippet](/youtube/partner/reference/rest/v1/assetSearch#AssetSnippet)`)` A list of asset resources that match the request criteria. |\n| `nextPageToken` | `string` The token that can be used as the value of the `pageToken` parameter to retrieve the next page of results. |\n\n### Authorization scopes\n\nRequires the following OAuth scope:\n\n- `https://www.googleapis.com/auth/youtubepartner`\n\nFor more information, see the [OAuth 2.0 Overview](/identity/protocols/OAuth2).\n\nOwnershipRestriction\n--------------------\n\nEnum of ownership restriction.\n\n| Enums ||\n|-------------------------------------|--------------------------------------------------------------------------------------------------|\n| `OWNERSHIP_RESTRICTION_UNSPECIFIED` | Default value. |\n| `MINE` | Find assets owned by the current user that match the search query. This is the default behavior. |\n| `NONE` | Find all assets that match the search query, regardless of owner. |\n\nSort\n----\n\nEnum of supported sorting orders in asset search list request.\n\n| Enums ||\n|-----------------------|--------------------------------------------------------------------------|\n| `SORT_UNSPECIFIED` | Default value. |\n| `CLAIMS` | Sort by the number of claims for each asset. |\n| `TIME` | Sort by the modification time for each asset. This is the default value. |\n| `VIEWS` | Sort by the approximate daily engaged views for each asset. |\n| `DAILY_ENGAGED_VIEWS` | Sort by the approximate daily engaged views for each asset. |"]]
