Method: claimSearch.list

    • This API endpoint allows you to retrieve a list of claims that match specific search criteria, including those associated with an asset or video, or based on a query string.

    • You can filter the claims by various parameters such as assetId , contentType , creation dates, status , and whether they are partner-uploaded.

    • The response body provides a paginated list of claim snippets, including details like the claim's kind, page information, and individual claim items, allowing navigation through results using nextPageToken and previousPageToken .

    • Sorting of the results can be performed by DATE or VIEW_COUNT , and the method used is set by the sort parameter.

    • The status parameter filters the claims based on their state, with options like ACTIVE , APPEALED , DISPUTED , and others.

    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 .
    DAILY_ENGAGED_VIEWS Resources are sorted from highest to lowest number of approximate daily engaged 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 .
    LIFETIME_ENGAGED_VIEWS Resources are sorted from highest to lowest number of approximate lifetime engaged 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.
    Design a Mobile Site
    View Site in Mobile | Classic
    Share by: