Method: claimSearch.list

Retrieves a list of claims that match the search criteria. You can search for claims that are associated with a specific asset or video or that match a specified query string.

HTTP request

GET https://youtubepartner.googleapis.com/youtube/partner/v1/claimSearch

The URL uses gRPC Transcoding syntax.

Query parameters

Parameters
assetId

string

The assetId parameter specifies the YouTube asset ID of the asset for which you are retrieving claims.
contentType

enum (ContentType)

The contentType parameter specifies the content type of claims that you want to retrieve.
createdAfter

string

The createdAfter parameter allows you to restrict the set of returned claims to ones created on or after the specified date (inclusive).
createdBefore

string

The createdBefore parameter allows you to restrict the set of returned claims to ones created before the specified date (exclusive).
inactiveReasons

string

The inactiveReasons parameter allows you to specify what kind of inactive claims you want to find based on the reasons why the claims became inactive.
includeThirdPartyClaims

boolean

Used along with the videoId parameter this parameter determines whether or not to include third party claims in the search results.
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.
origin

string

The origin parameter specifies the origins you want to find claims for. It is a comma-separated list of origin values.
pageToken

string

The pageToken parameter specifies a token that identifies a particular page of results to return. For example, set this parameter to the value of the nextPageToken value from the previous API response to retrieve the next page of search results.
partnerUploaded

boolean

The partnerUploaded parameter specifies whether you want to filter your search results to only partner uploaded or non partner uploaded claims.
q

string

The q parameter specifies the query string to use to filter search results. YouTube searches for the query string in the following claim fields: videoTitle, video_keywords, user_name, isrc, iswc, grid, customId, and in the content owner's email address.
referenceId

string

The referenceId parameter specifies the YouTube reference ID of the reference for which you are retrieving claims.
sort

enum (Sort)

The sort parameter specifies the method that will be used to order resources in the API response. The default value is date. However, if the status parameter value is either appealed, disputed, pending, potential, or routedForReview, then results will be sorted by the time that the claim review period expires.
status

enum (Status)

The status parameter restricts your results to only claims in the specified status.
statusModifiedAfter

string

The statusModifiedAfter parameter allows you to restrict the result set to only include claims that have had their status modified on or after the specified date (inclusive). The date specified must be on or after June 30, 2016 (2016-06-30). The parameter value's format is YYYY-MM-DD.
statusModifiedBefore

string

The statusModifiedBefore parameter allows you to restrict the result set to only include claims that have had their status modified before the specified date (exclusive). The date specified must be on or after July 1, 2016 (2016-07-01). The parameter value's format is YYYY-MM-DD.
videoId

string

The videoId parameter specifies comma-separated list of YouTube video IDs for which you are retrieving claims.
isVideoShortsEligible

boolean

The isVideoShortsEligible parameter allows you to restrict the result set to only include claims that are on videos that are YouTube Shorts eligible, or to exclude them. If unspecified, no filtering will be performed based on YouTube Shorts eligibility.

Request body

The request body must be empty.

Response body

A paginated list of claim snippets returned in response to a claimSearch.list call.

If successful, the response body contains data with the following structure:

JSON representation 
{
  "kind": string,
  "pageInfo": {
    object (PageInfo)
  },
  "items": [
    {
      object (ClaimSnippet)
    }
  ],
  "nextPageToken": string,
  "previousPageToken": string
}
Fields
kind

string

The type of the API response. For this operation, the value is youtubePartner#claimSnippetList.
pageInfo

object (PageInfo)

The pageInfo object encapsulates paging information for the result set.
items[]

object (ClaimSnippet)

A list of claims 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 in the result set.
previousPageToken

string

The token that can be used as the value of the pageToken parameter to retrieve the previous page in the result set.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/youtubepartner

For more information, see the OAuth 2.0 Overview.

ContentType

Enum of content type.

Enums
CONTENT_TYPE_UNSPECIFIED Default value.
AUDIO Restrict results to audio-only claims.
AUDIOVISUAL Restrict results to audiovisual claims.
VISUAL Restrict results to video-only claims.

Sort

Supported sorting orders.

Enums
SORT_UNSPECIFIED Default value.
DATE Resources are sorted in reverse chronological order (from newest to oldest) based on the dates they were created. This value is not applicable if the status parameter is set to any of the following values: appealed, disputed, pending, potential, or routedForReview.
VIEW_COUNT Resources are sorted from highest to lowest number of views for the claimed content. This value is not applicable if the status parameter is set to any of the following values: appealed, disputed, pending, potential, or routedForReview.

Status

Enum of claim status.

Enums
STATUS_UNSPECIFIED Default value.
ACTIVE Restrict results to claims with active status.
APPEALED Restrict results to claims with appealed status.
DISPUTED Restrict results to claims with disputed status.
INACTIVE Restrict results to claims with inactive status.
PENDING Restrict results to claims with pending status.
POTENTIAL Restrict results to claims with potetial status.
ROUTED_FOR_REVIEW Restrict results to claims that require review based on a match policy rule.
TAKEDOWN Restrict results to claims with takedown status.
SHORT_MATCH Restrict results to claims where the matching segment is too short for us to be confident that it should be made.
YOUTUBE_PARTNER Restrict results to claims about videos that were uploaded to a channel owned by a YT partner.
LOW_CONFIDENCE Restrict results to claims with low confidence for various reasons, including low match score, low trust score, high view count, etc.
YT_MONETIZATION_POLICY Restrict results to 3rd claims that are suspected of being actually first party claims done through music aggregators (allowing creators to monetize without having to get into YPP).
RETROACTIVE_BLOCK Restrict results to low confidence claims made as part of legacy block.