{"openapi": "3.0.3", "info": {"version": "3.0.0", "title": "Tubular API", "description": "Tubular API"}, "servers": [{"url": "https://tubularlabs.com/api/v3", "description": "Tubular Production server"}], "paths": {"/auth.test": {"x-requires": ["api_enabled"], "x-group": ["asset"], "post": {"summary": "Checks whether the supplied API key is valid.", "parameters": [{"in": "header", "description": "Tubular API key.", "name": "Api-Key", "schema": {"type": "string"}}], "requestBody": {"description": "Optional request body. A token parameter can be provided to test a specific authentication token instead of the one in the header.\n", "content": {"application/json": {"schema": {"type": "object", "description": "Optional authentication token.", "properties": {"token": {"type": "string", "description": "Authentication token (include in HTTP header if not specified)."}}}}}}, "responses": {"200": {"description": "The supplied API key is valid.", "headers": {"Tubular-RateLimit-Overall-Limit": {"description": "The overall rate limit is 60 requests per minute. This rate limit applies to any combination of API methods that are called within a trailing 1-minute timeframe.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Overall-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Limit": {"description": "The concurrency rate limit is set to 1. This means that no more than a single request can be made at a time (i.e., in parallel). Attempting to issue a video.search request while a video.facets request is still running, for example will cause the video.search request to return a rate_limited error.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Remaining": {"description": "Number of concurrent requests available for use.", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"type": "object", "properties": {"ok": {"type": "boolean", "description": "Will always be true to signify that the API key is valid."}}}}}}, "400": {"description": "The supplied API key is invalid."}}}}, "/health": {"x-group": ["asset"], "get": {"summary": "Returns the health status of the API service.", "responses": {"200": {"description": "The API service is healthy.", "content": {"application/json": {"schema": {"type": "object", "properties": {"ok": {"type": "boolean", "description": "Indicates the request was successful.", "example": true}, "status": {"type": "string", "description": "The health status of the service.", "example": "healthy"}}}}}}}}}, "/rate_limit.details": {"x-requires": ["api_intelligence"], "x-group": ["asset"], "post": {"summary": "Returns current state of rate limits and quota.", "parameters": [{"in": "header", "description": "Tubular API key.", "name": "Api-Key", "schema": {"type": "string"}}], "requestBody": {"description": "No request body is required for this endpoint.\n", "content": {"application/json": {"schema": {"type": "object", "description": "Empty request body."}}}}, "responses": {"200": {"description": "Status of operation", "headers": {"Tubular-RateLimit-Overall-Limit": {"description": "The overall rate limit is 60 requests per minute. This rate limit applies to any combination of API methods that are called within a trailing 1-minute timeframe.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Overall-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Limit": {"description": "The concurrency rate limit is set to 1. This means that no more than a single request can be made at a time (i.e., in parallel). Attempting to issue a video.search request while a video.facets request is still running, for example will cause the video.search request to return a rate_limited error.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Remaining": {"description": "Number of concurrent requests available for use.", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"type": "object", "properties": {"ok": {"type": "boolean", "description": "Whether the request was successful."}, "rate_limits": {"type": "object", "description": "Rate limit and quota details for the current account.", "properties": {"Concurrency": {"type": "object", "description": "Concurrent request limits.", "properties": {"limit": {"type": "integer", "description": "Maximum number of parallel requests allowed.", "example": 4}, "remaining": {"type": "integer", "description": "Number of concurrent request slots available.", "example": 4}}}, "Overall": {"type": "object", "description": "Overall API request rate limit over a 60-second rolling window.", "properties": {"limit": {"type": "integer", "description": "Maximum number of requests allowed per window.", "example": 60}, "remaining": {"type": "integer", "description": "Number of requests remaining in the current window.", "example": 60}}}, "FacetSummary": {"type": "object", "description": "Rate limit for facet and summary requests over a 60-second rolling window.", "properties": {"limit": {"type": "integer", "description": "Maximum number of facet/summary requests allowed per window.", "example": 60}, "remaining": {"type": "integer", "description": "Number of facet/summary requests remaining.", "example": 60}}}, "AudienceOverlap": {"type": "object", "description": "Rate limit for audience overlap requests over a 60-second rolling window.", "properties": {"limit": {"type": "integer", "description": "Maximum number of audience overlap requests allowed per window.", "example": 1}, "remaining": {"type": "integer", "description": "Number of audience overlap requests remaining.", "example": 1}}}, "UniqueCreatorLimit": {"type": "object", "description": "Limit on the number of unique creators that can be queried during the current billing period.", "properties": {"limit": {"type": "integer", "description": "Maximum number of unique creators allowed.", "example": 10000000}, "remaining": {"type": "integer", "description": "Number of unique creators remaining.", "example": 10000000}, "expires": {"type": "string", "description": "Billing-period reset date for this limit (YYYY-MM-DD).", "example": "2026-03-31"}}}, "UniqueVideoLimit": {"type": "object", "description": "Limit on the number of unique videos that can be queried during the current billing period.", "properties": {"limit": {"type": "integer", "description": "Maximum number of unique videos allowed.", "example": 100000000}, "remaining": {"type": "integer", "description": "Number of unique videos remaining.", "example": 100000000}, "expires": {"type": "string", "description": "Billing-period reset date for this limit (YYYY-MM-DD).", "example": "2026-03-31"}}}, "Tubular-Quota-Used": {"type": "integer", "description": "Total quota units consumed in the current billing period.", "example": 490}, "Tubular-Quota-Limit": {"type": "integer", "description": "Total quota units available for the billing period.", "example": 250000000}}}}}}}}, "429": {"description": "The query is rate-limited.", "headers": {"Tubular-RateLimit-Overall-Limit": {"description": "The overall rate limit is 60 requests per minute. This rate limit applies to any combination of API methods that are called within a trailing 1-minute timeframe.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Overall-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Limit": {"description": "The concurrency rate limit is set to 1. This means that no more than a single request can be made at a time (i.e., in parallel). Attempting to issue a video.search request while a video.facets request is still running, for example will cause the video.search request to return a rate_limited error.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Remaining": {"description": "Number of concurrent requests available for use.", "schema": {"type": "integer"}}}}}}}, "/video.search": {"x-requires": ["api_intelligence"], "x-group": ["data", "video"], "post": {"summary": "Returns a list of videos, including video identifiers and details, for videos matching a specific search query, which can be composed of search terms and/or filters.", "parameters": [{"in": "header", "description": "Tubular API key.", "name": "Api-Key", "schema": {"type": "string"}}], "requestBody": {"content": {"application/json": {"schema": {"type": "object", "required": ["query", "fields"], "properties": {"query": {"type": "object", "description": "Defines search criteria that combines include and exclude filters.", "properties": {"savedsearch_id": {"type": "integer", "x-component": "select", "description": "Video saved search id", "x-source": "qb/getVideoSavedSearches"}, "include_filter": {"type": "object", "description": "A video filter to be included by the query. Defaults to include everything if not specified.", "properties": {"search": {"type": "string", "description": "The search text string to be included in the filter for searching across video titles. This string may include optional boolean search operators as described by the Help Center. Defaults to empty string if not specified.", "x-hint": "Use AND and OR operators", "x-placeholder": "I'm a placeholder"}, "search_description": {"type": "boolean", "description": "Controls whether to search the video descriptions when providing a search string parameter. Defaults to false if not specified."}, "search_keywords": {"type": "boolean", "description": "Controls whether to search the video keywords when providing a search string parameter. Defaults to false if not specified."}, "search_topics": {"type": "boolean", "description": "Controls whether to search the video topics when providing a search string parameter. Defaults to true if not specified."}, "video_gids": {"type": "array", "x-component": "select", "x-add": true, "description": "A list of specific videos to fetch. Each video is represent in the form of GID which consists of a platform prefix and original video ID. The prefixes are <ul> <li><b>ytv_</b> - YouTube</li> <li><b>fbv_</b> - Facebook</li> <li><b>igv_</b> - Instagram</li> <li><b>twv_</b> - Twitter</li> <li><b>tkv_</b> - TikTok</li> <li><b>ttv_</b> - Twitch</li> </ul> For example, a gid for Gangnam Style video would be <b>ytv_9bZkp7q19f0</b>", "items": {"type": "string"}}, "video_platforms": {"type": "array", "x-component": "select", "description": "An array of social platforms to use in the filter.", "x-options": {"youtube": "YouTube", "facebook": "Facebook", "instagram": "Instagram", "twitch": "Twitch", "tiktok": "TikTok"}, "items": {"type": "string"}}, "video_upload_date": {"type": "object", "x-component": "dateRange", "description": "Applies a date range limit to the date a video was uploaded. Note that this parameter has a large impact on query response times. In general, <b>the larger</b> the time span the more time the query will take to complete.\nInclude filters will default to a minimum upload date of 'last_90' if not specified. Exclude filters must specify a minimum upload date when providing the video_upload_date parameter. Due to performance reasons, this date range cannot span beyond the value allowed by your plan. To query a larger date range, you will need to issue multiple queries each with a different range and combine results.", "properties": {"min": {"type": "string", "description": "The minimum date to be included as part of a range of dates in \"YYYY-MM-DD\"", "x-component": "date"}, "max": {"type": "string", "description": "The maximum date to be included as part of a range of dates in \"YYYY-MM-DD\" format.", "x-component": "date"}}, "x-options": [{"label": "Last day", "value": "last_day"}, {"label": "Last week", "value": "last_7"}, {"label": "Last 30 days", "value": "last_30"}, {"label": "Last 90 days", "value": "last_90"}, {"label": "Last year", "value": "last_1_y"}, {"label": "Last two years", "value": "last_2_y"}, {"label": "Last three years", "value": "last_3_y"}, {"label": "All time", "value": "all_time"}, {"label": "Custom Date Range", "value": {"handler": "custom"}}]}, "video_duration": {"type": "object", "x-component": "integerRange", "description": "Applies a duration limit in seconds to use in the filter.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "video_was_live": {"type": "boolean", "description": "Specifies whether to include videos that were lived streamed. Ignored if not specified."}, "video_is_made_for_kids": {"type": "boolean", "description": "Specifies whether to include YouTube videos that were marked as \"Made for Kids\". Ignored if not specified."}, "video_is_reel": {"type": "boolean", "description": "Specifies whether to include Instagram Reel videos. Ignored if not specified."}, "video_is_360": {"type": "boolean", "description": "Specifies whether to include videos in the 360 (spherical) format. Ignored if not specified."}, "video_is_noteworthy": {"type": "boolean", "description": "Experimental feature. Specifies whether to include videos that get more views than expected given the creator's followers count and do not primarily get views from advertising. Ignored if not specified."}, "video_languages": {"type": "array", "description": "Specifies the language of the video to use in the filter. Note that available languages are currently not obtainable via a VideoFacets query. Language strings are represented as <a href=\"https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes\">ISO 639-1</a> two-letter language codes. Defaults to all languages if not specified.", "items": {"type": "string"}, "x-component": "select", "x-autocomplete": "qb/getLanguages"}, "video_list": {"type": "integer", "description": "A video custom list identifier to use in the filter. A video list represents a custom list of videos. These custom lists can be created and modified programmatically.\nSee the Custom List Methods section of the API documentation for more details. Available video lists can be obtained via the custom_list.enumerate method. Defaults to not include a video list.", "x-component": "select", "x-source": "qb/getVideoLists"}, "video_lists": {"type": "array", "description": "One or more video custom list identifiers to use in the filter. A video list represents a custom list of videos. These custom lists can be created and modified programmatically. See the Custom List Methods section of the API documentation for more details. Available video lists can be obtained via the custom_list.enumerate method. Defaults to not include a video list.", "x-component": "select", "x-source": "qb/getVideoLists", "items": {"type": "integer"}}, "video_categories": {"type": "array", "description": "Specifies a list of category names to use in the filtering. Defaults to all categories if not specified. Currently we support categories for Youtube and Facebook platforms only.", "items": {"type": "string"}, "x-component": "select", "x-autocomplete": "qb/searchVideoCategories"}, "video_entities": {"type": "array", "x-component": "select", "description": "Specifies a list of video topic identifiers to use in the filters. Defaults to all topics if not specified.", "items": {"type": "integer"}, "x-autocomplete": "qb/searchVideoTopics", "x-add": true}, "video_views": {"type": "object", "x-component": "integerRange", "description": "Applies a view limit (total number of views) to use in the filter. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "video_engagements": {"type": "object", "x-component": "integerRange", "description": "Applies a cross-platform enagement limit to use in the filter. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "hashtags": {"type": "array", "description": "Show only videos that have one or more", "x-component": "select", "x-add": true, "items": {"type": "string"}}, "mentions": {"type": "array", "description": "Show only videos that have one or more @mention in the description.", "x-component": "select", "x-add": true, "items": {"type": "string"}}, "challenges": {"type": "array", "description": "Show only videos that are part of a given challenge (TikTok only).", "x-component": "select", "x-add": true, "items": {"type": "string"}}, "audio_ids": {"type": "array", "description": "Show only videos that use one or more audio IDs (TikTok only).", "x-component": "select", "x-add": true, "items": {"type": "string"}}, "audio_titles": {"type": "array", "description": "Show only videos that use one or more audio title (TikTok only).", "x-component": "select", "x-add": true, "x-autocomplete": "qb/searchAudioTitles", "items": {"type": "string"}}, "audio_authors": {"type": "array", "description": "Show only videos that use audio of one or more audio authors (TikTok only).", "x-component": "select", "x-add": true, "x-autocomplete": "qb/searchAudioAuthors", "items": {"type": "string"}}, "audio_is_original": {"type": "boolean", "description": "Show only videos that use original audio (TikTok only)."}, "creator_types": {"type": "array", "description": "An array of creator types to use in the filter.", "x-component": "select", "x-options": {"influencer": "Influencer", "brand": "Brand", "media company": "Media Company", "aggregator": "Aggregator"}, "items": {"type": "string"}}, "creator_industries": {"type": "array", "description": "An array of creator industry identifiers to use in the filter. Defaults to all creator industries if not specified. Relevant for Brands.", "x-component": "select", "x-options": {"1": "Technology", "2": "Travel & Leisure", "3": "Music", "4": "CPG", "5": "Automotive", "6": "Financial & Insurance", "7": "Toys & Board Games", "8": "Media", "9": "Retail", "10": "Logistics & Heavy Industry", "11": "Other", "12": "Apparel & Accessories", "13": "Beverages", "14": "Personal Care & Health", "15": "Education", "16": "Public Service & Nonprofit", "17": "Food", "19": "Telecom", "20": "Pets", "21": "Sports Teams & Leagues", "22": "Gaming", "23": "Energy", "25": "Electronics", "27": "Broadcast, Cable, Radio, Film", "28": "Digital First Media", "29": "Magazine & Newspaper", "30": "Beauty"}, "items": {"type": "integer"}}, "creator_properties": {"type": "array", "x-component": "select", "description": "An array of creator property identifiers to use in the filter. Available creator properties can be obtained via a VideoFacets query. Defaults to all creator properties if not specified.", "x-autocomplete": "qb/searchProperties", "items": {"type": "integer"}}, "creator_list": {"type": "integer", "description": "A creator custom list identifier to use in the filter. A creator list represents a custom list of creators. These custom lists can be created and modified programmatically. See the Custom List section of the API documentation for more details. Available creator lists can be obtained via the custom_list.enumerate method. Defaults to not include a creator list.", "x-component": "select", "x-source": "qb/getCreatorLists"}, "creator_lists": {"type": "array", "description": "One or more creator custom list identifiers to use in the filter. A creator list represents a custom list of creators. These custom lists can be created and modified programmatically. See the Custom List section of the API documentation for more details. Available creator lists can be obtained via the custom_list.enumerate method. Defaults to not include a creator list.", "x-component": "select", "x-source": "qb/getCreatorLists", "items": {"type": "integer"}}, "creators": {"type": "array", "x-component": "select", "description": "An array of creator identifiers to use in the filter. Available creator identifiers can be obtained via the VideoFacets method or by searching for a particular creator via the CreatorSearch method. Defaults to all creators.", "x-add": true, "x-autocomplete": "qb/searchCreators", "items": {"type": "string"}}, "creator_accounts": {"type": "array", "x-component": "select", "description": "An array of creator social account identifiers to use in the filter. Available creator account identifiers can be obtained via the VideoFacets method or by the list of social accounts associated with a particular creator obtained via the CreatorDetails query. Defaults to all creator accounts if not specified.", "items": {"type": "string"}, "x-add": true}, "creator_account_followers": {"type": "object", "x-component": "integerRange", "description": "Applies a range limit to the follower count for the creator's social account that published a video (i.e., only videos whose follower counts fall within the range will be included). Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "creator_account_countries": {"type": "array", "description": "Specifies the countries associated with the creator account when limiting videos (e.g., only videos whose account are associated with the United States and France). Unlike creator_countries, this filter is applied to the country value set by the original platform. Country strings are represented as two-letter ISO 3166-1 alpha-2 codes. Defaults to all countries if not specified.", "items": {"type": "string"}, "x-component": "select", "x-autocomplete": "qb/getCountries"}, "creator_account_categories": {"type": "array", "description": "Specifies the categories associated with the creator account when limiting videos. Unlike video_categories, this filter is applied to the category value set by the original platform.", "items": {"type": "integer"}, "x-component": "select", "x-options": {"1": "Film & Animation", "2": "Autos & Vehicles", "10": "Music", "15": "Pets & Animals", "17": "Sports", "19": "Travel & Events", "20": "Gaming", "22": "People & Blogs", "23": "Comedy", "24": "Entertainment", "25": "News & Politics", "26": "Howto & Style", "27": "Education", "28": "Science & Technology", "29": "Nonprofits & Activism"}}, "creator_genres": {"type": "array", "description": "An array of content genre identifiers to use in the filter. Available content genre identifiers can be obtained via a VideoFacets query. Defaults to all content genres if not specified.", "x-component": "select", "x-options": {"2": "Travel", "3": "Music & Dance", "4": "Sports", "5": "Animals & Pets", "7": "People & Blogs", "9": "Cars, Trucks & Racing", "11": "Business", "13": "Kids Entertainment & Animation", "14": "Education", "15": "Food & Drink", "16": "Fashion & Style", "19": "Health, Fitness & Self Help", "21": "Home & DIY", "22": "News & Politics", "23": "Beauty", "24": "Film & Movies", "27": "Gaming", "32": "Family & Parenting", "33": "Science & Tech", "36": "Entertainment", "37": "General Interest"}, "items": {"type": "integer"}}, "creator_facebook_watch": {"type": "boolean", "description": "Limits the creators to those that publish a show on Facebook watch. Defaults to include all if not specified. Value can only be true or unspecified."}, "creator_countries": {"type": "array", "description": "Specifies the countries associated with the creator's accounts when limiting videos (e.g., only videos whose accounts are associated with the United States and France). Available creator countries can be obtained via a VideoFacets query. Country strings are represented as two-letter ISO 3166-1 alpha-2 codes. Defaults to all countries if not specified.", "items": {"type": "string"}, "x-component": "select", "x-autocomplete": "qb/getCountries"}, "shorts_format": {"type": "array", "description": "Limits videos to platform-specific short formats.", "items": {"type": "string"}, "x-component": "select", "x-options": {"yt_shorts": "YouTube Shorts"}}}}, "exclude_filter": {"type": "object", "description": "A video filter to be excluded by the query. Defaults to exclude no videos if not specified.", "properties": {"search": {"type": "string", "description": "The search text string to be included in the filter for searching across video titles. This string may include optional boolean search operators as described by the Help Center. Defaults to empty string if not specified.", "x-hint": "Use AND and OR operators", "x-placeholder": "I'm a placeholder"}, "search_description": {"type": "boolean", "description": "Controls whether to search the video descriptions when providing a search string parameter. Defaults to false if not specified."}, "search_keywords": {"type": "boolean", "description": "Controls whether to search the video keywords when providing a search string parameter. Defaults to false if not specified."}, "search_topics": {"type": "boolean", "description": "Controls whether to search the video topics when providing a search string parameter. Defaults to true if not specified."}, "video_gids": {"type": "array", "x-component": "select", "x-add": true, "description": "A list of specific videos to fetch. Each video is represent in the form of GID which consists of a platform prefix and original video ID. The prefixes are <ul> <li><b>ytv_</b> - YouTube</li> <li><b>fbv_</b> - Facebook</li> <li><b>igv_</b> - Instagram</li> <li><b>twv_</b> - Twitter</li> <li><b>tkv_</b> - TikTok</li> <li><b>ttv_</b> - Twitch</li> </ul> For example, a gid for Gangnam Style video would be <b>ytv_9bZkp7q19f0</b>", "items": {"type": "string"}}, "video_platforms": {"type": "array", "x-component": "select", "description": "An array of social platforms to use in the filter.", "x-options": {"youtube": "YouTube", "facebook": "Facebook", "instagram": "Instagram", "twitch": "Twitch", "tiktok": "TikTok"}, "items": {"type": "string"}}, "video_upload_date": {"type": "object", "x-component": "dateRange", "description": "Applies a date range limit to the date a video was uploaded. Note that this parameter has a large impact on query response times. In general, <b>the larger</b> the time span the more time the query will take to complete.\nInclude filters will default to a minimum upload date of 'last_90' if not specified. Exclude filters must specify a minimum upload date when providing the video_upload_date parameter. Due to performance reasons, this date range cannot span beyond the value allowed by your plan. To query a larger date range, you will need to issue multiple queries each with a different range and combine results.", "properties": {"min": {"type": "string", "description": "The minimum date to be included as part of a range of dates in \"YYYY-MM-DD\"", "x-component": "date"}, "max": {"type": "string", "description": "The maximum date to be included as part of a range of dates in \"YYYY-MM-DD\" format.", "x-component": "date"}}, "x-options": [{"label": "Last day", "value": "last_day"}, {"label": "Last week", "value": "last_7"}, {"label": "Last 30 days", "value": "last_30"}, {"label": "Last 90 days", "value": "last_90"}, {"label": "Last year", "value": "last_1_y"}, {"label": "Last two years", "value": "last_2_y"}, {"label": "Last three years", "value": "last_3_y"}, {"label": "All time", "value": "all_time"}, {"label": "Custom Date Range", "value": {"handler": "custom"}}]}, "video_duration": {"type": "object", "x-component": "integerRange", "description": "Applies a duration limit in seconds to use in the filter.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "video_was_live": {"type": "boolean", "description": "Specifies whether to include videos that were lived streamed. Ignored if not specified."}, "video_is_made_for_kids": {"type": "boolean", "description": "Specifies whether to include YouTube videos that were marked as \"Made for Kids\". Ignored if not specified."}, "video_is_reel": {"type": "boolean", "description": "Specifies whether to include Instagram Reel videos. Ignored if not specified."}, "video_is_360": {"type": "boolean", "description": "Specifies whether to include videos in the 360 (spherical) format. Ignored if not specified."}, "video_is_noteworthy": {"type": "boolean", "description": "Experimental feature. Specifies whether to include videos that get more views than expected given the creator's followers count and do not primarily get views from advertising. Ignored if not specified."}, "video_languages": {"type": "array", "description": "Specifies the language of the video to use in the filter. Note that available languages are currently not obtainable via a VideoFacets query. Language strings are represented as <a href=\"https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes\">ISO 639-1</a> two-letter language codes. Defaults to all languages if not specified.", "items": {"type": "string"}, "x-component": "select", "x-autocomplete": "qb/getLanguages"}, "video_list": {"type": "integer", "description": "A video custom list identifier to use in the filter. A video list represents a custom list of videos. These custom lists can be created and modified programmatically.\nSee the Custom List Methods section of the API documentation for more details. Available video lists can be obtained via the custom_list.enumerate method. Defaults to not include a video list.", "x-component": "select", "x-source": "qb/getVideoLists"}, "video_lists": {"type": "array", "description": "One or more video custom list identifiers to use in the filter. A video list represents a custom list of videos. These custom lists can be created and modified programmatically. See the Custom List Methods section of the API documentation for more details. Available video lists can be obtained via the custom_list.enumerate method. Defaults to not include a video list.", "x-component": "select", "x-source": "qb/getVideoLists", "items": {"type": "integer"}}, "video_categories": {"type": "array", "description": "Specifies a list of category names to use in the filtering. Defaults to all categories if not specified. Currently we support categories for Youtube and Facebook platforms only.", "items": {"type": "string"}, "x-component": "select", "x-autocomplete": "qb/searchVideoCategories"}, "video_entities": {"type": "array", "x-component": "select", "description": "Specifies a list of video topic identifiers to use in the filters. Defaults to all topics if not specified.", "items": {"type": "integer"}, "x-autocomplete": "qb/searchVideoTopics", "x-add": true}, "video_views": {"type": "object", "x-component": "integerRange", "description": "Applies a view limit (total number of views) to use in the filter. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "video_engagements": {"type": "object", "x-component": "integerRange", "description": "Applies a cross-platform enagement limit to use in the filter. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "hashtags": {"type": "array", "description": "Show only videos that have one or more", "x-component": "select", "x-add": true, "items": {"type": "string"}}, "mentions": {"type": "array", "description": "Show only videos that have one or more @mention in the description.", "x-component": "select", "x-add": true, "items": {"type": "string"}}, "challenges": {"type": "array", "description": "Show only videos that are part of a given challenge (TikTok only).", "x-component": "select", "x-add": true, "items": {"type": "string"}}, "audio_ids": {"type": "array", "description": "Show only videos that use one or more audio IDs (TikTok only).", "x-component": "select", "x-add": true, "items": {"type": "string"}}, "audio_titles": {"type": "array", "description": "Show only videos that use one or more audio title (TikTok only).", "x-component": "select", "x-add": true, "x-autocomplete": "qb/searchAudioTitles", "items": {"type": "string"}}, "audio_authors": {"type": "array", "description": "Show only videos that use audio of one or more audio authors (TikTok only).", "x-component": "select", "x-add": true, "x-autocomplete": "qb/searchAudioAuthors", "items": {"type": "string"}}, "audio_is_original": {"type": "boolean", "description": "Show only videos that use original audio (TikTok only)."}, "creator_types": {"type": "array", "description": "An array of creator types to use in the filter.", "x-component": "select", "x-options": {"influencer": "Influencer", "brand": "Brand", "media company": "Media Company", "aggregator": "Aggregator"}, "items": {"type": "string"}}, "creator_industries": {"type": "array", "description": "An array of creator industry identifiers to use in the filter. Defaults to all creator industries if not specified. Relevant for Brands.", "x-component": "select", "x-options": {"1": "Technology", "2": "Travel & Leisure", "3": "Music", "4": "CPG", "5": "Automotive", "6": "Financial & Insurance", "7": "Toys & Board Games", "8": "Media", "9": "Retail", "10": "Logistics & Heavy Industry", "11": "Other", "12": "Apparel & Accessories", "13": "Beverages", "14": "Personal Care & Health", "15": "Education", "16": "Public Service & Nonprofit", "17": "Food", "19": "Telecom", "20": "Pets", "21": "Sports Teams & Leagues", "22": "Gaming", "23": "Energy", "25": "Electronics", "27": "Broadcast, Cable, Radio, Film", "28": "Digital First Media", "29": "Magazine & Newspaper", "30": "Beauty"}, "items": {"type": "integer"}}, "creator_properties": {"type": "array", "x-component": "select", "description": "An array of creator property identifiers to use in the filter. Available creator properties can be obtained via a VideoFacets query. Defaults to all creator properties if not specified.", "x-autocomplete": "qb/searchProperties", "items": {"type": "integer"}}, "creator_list": {"type": "integer", "description": "A creator custom list identifier to use in the filter. A creator list represents a custom list of creators. These custom lists can be created and modified programmatically. See the Custom List section of the API documentation for more details. Available creator lists can be obtained via the custom_list.enumerate method. Defaults to not include a creator list.", "x-component": "select", "x-source": "qb/getCreatorLists"}, "creator_lists": {"type": "array", "description": "One or more creator custom list identifiers to use in the filter. A creator list represents a custom list of creators. These custom lists can be created and modified programmatically. See the Custom List section of the API documentation for more details. Available creator lists can be obtained via the custom_list.enumerate method. Defaults to not include a creator list.", "x-component": "select", "x-source": "qb/getCreatorLists", "items": {"type": "integer"}}, "creators": {"type": "array", "x-component": "select", "description": "An array of creator identifiers to use in the filter. Available creator identifiers can be obtained via the VideoFacets method or by searching for a particular creator via the CreatorSearch method. Defaults to all creators.", "x-add": true, "x-autocomplete": "qb/searchCreators", "items": {"type": "string"}}, "creator_accounts": {"type": "array", "x-component": "select", "description": "An array of creator social account identifiers to use in the filter. Available creator account identifiers can be obtained via the VideoFacets method or by the list of social accounts associated with a particular creator obtained via the CreatorDetails query. Defaults to all creator accounts if not specified.", "items": {"type": "string"}, "x-add": true}, "creator_account_followers": {"type": "object", "x-component": "integerRange", "description": "Applies a range limit to the follower count for the creator's social account that published a video (i.e., only videos whose follower counts fall within the range will be included). Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "creator_account_countries": {"type": "array", "description": "Specifies the countries associated with the creator account when limiting videos (e.g., only videos whose account are associated with the United States and France). Unlike creator_countries, this filter is applied to the country value set by the original platform. Country strings are represented as two-letter ISO 3166-1 alpha-2 codes. Defaults to all countries if not specified.", "items": {"type": "string"}, "x-component": "select", "x-autocomplete": "qb/getCountries"}, "creator_account_categories": {"type": "array", "description": "Specifies the categories associated with the creator account when limiting videos. Unlike video_categories, this filter is applied to the category value set by the original platform.", "items": {"type": "integer"}, "x-component": "select", "x-options": {"1": "Film & Animation", "2": "Autos & Vehicles", "10": "Music", "15": "Pets & Animals", "17": "Sports", "19": "Travel & Events", "20": "Gaming", "22": "People & Blogs", "23": "Comedy", "24": "Entertainment", "25": "News & Politics", "26": "Howto & Style", "27": "Education", "28": "Science & Technology", "29": "Nonprofits & Activism"}}, "creator_genres": {"type": "array", "description": "An array of content genre identifiers to use in the filter. Available content genre identifiers can be obtained via a VideoFacets query. Defaults to all content genres if not specified.", "x-component": "select", "x-options": {"2": "Travel", "3": "Music & Dance", "4": "Sports", "5": "Animals & Pets", "7": "People & Blogs", "9": "Cars, Trucks & Racing", "11": "Business", "13": "Kids Entertainment & Animation", "14": "Education", "15": "Food & Drink", "16": "Fashion & Style", "19": "Health, Fitness & Self Help", "21": "Home & DIY", "22": "News & Politics", "23": "Beauty", "24": "Film & Movies", "27": "Gaming", "32": "Family & Parenting", "33": "Science & Tech", "36": "Entertainment", "37": "General Interest"}, "items": {"type": "integer"}}, "creator_facebook_watch": {"type": "boolean", "description": "Limits the creators to those that publish a show on Facebook watch. Defaults to include all if not specified. Value can only be true or unspecified."}, "creator_countries": {"type": "array", "description": "Specifies the countries associated with the creator's accounts when limiting videos (e.g., only videos whose accounts are associated with the United States and France). Available creator countries can be obtained via a VideoFacets query. Country strings are represented as two-letter ISO 3166-1 alpha-2 codes. Defaults to all countries if not specified.", "items": {"type": "string"}, "x-component": "select", "x-autocomplete": "qb/getCountries"}, "shorts_format": {"type": "array", "description": "Limits videos to platform-specific short formats.", "items": {"type": "string"}, "x-component": "select", "x-options": {"yt_shorts": "YouTube Shorts"}}}}}}, "fields": {"type": "array", "x-component": "select", "items": {"type": "string"}, "description": "A list of extra details to fetch for every video search result.", "x-options": {"views_gain": {"label": "Views Gain", "description": "Views gained over `sort_date_range`"}, "engagements_gain": {"label": "Engagements Gain", "description": "Engagements gained over `sort_date_range`"}, "video_id": {"label": "Video ID", "description": "Video identifier for a particular video."}, "title": {"label": "Title", "description": "The title of the video."}, "description": {"label": "Description", "description": "The description of the video."}, "duration": {"label": "Duration", "description": "The duration of the video in seconds."}, "views": {"label": "Views", "description": "Total number of video views. Note that this value will be null for videos from certain platforms such as Twitter, Twitch for which Tubular currently does not collect views. In addition, for Youtube Shorts views metric counts the number of times a Short starts to play or replay."}, "engagements": {"label": "Engagements", "description": "JSON object representing engagement data for this video broken down by platform."}, "tvr": {"label": "TVR", "description": "JSON object representing the Tubular Video Ratings associated with this video."}, "language": {"label": "Language", "description": "ISO 639-1 two-letter language code that specifies the language used for this video."}, "publish_date": {"label": "Publish Date", "description": "Date in YYYY-MM-DD format when a video was published"}, "publish_timestamp": {"label": "Publish Timestamp", "description": "Timestamp in YYYY-MM-DD HH:MM:SS format when a video was published"}, "publisher": {"label": "Publisher", "description": "JSON object representing information about the creator that published the video."}, "thumbnail_url": {"label": "Thumbnail", "description": "The URL of the thumbnail image for this video."}, "video_url": {"label": "Video URL", "description": "The URL of the video."}, "video_was_live": {"label": "Video was live", "description": "Specifies whether a video was lived streamed."}, "video_is_reel": {"label": "Video is Reel", "description": "Specifies whether a video is Instagram Reel."}, "video_is_360": {"label": "Video is in 360 format", "description": "Specifies whether a video is spherical."}, "video_is_made_for_kids": {"label": "Video is made for kids", "description": "Specifies whether a video is marked as kids content."}, "youtube_category": {"label": "YouTube Category", "description": "The YouTube category used when uploading the video. Empty for other platform."}, "topics": {"label": "Topics", "description": "A list of JSON objects representing legacy topics associated with this video."}, "categories": {"label": "Categories", "description": "A list of JSON objects representing categories associated with this video."}, "entities": {"label": "Video Topics (new)", "description": "A list of JSON objects representing granular video topics associated with this video."}, "keywords": {"label": "Keywords", "description": "A list of keywords of the video if available on a platform."}, "hashtags": {"label": "Hashtags", "description": "A list of hashtags extracted from a video description."}, "mentions": {"label": "Mentions", "description": "A list of mentions extracted from a description. A word prefixed with @ is considered a mention."}, "audio": {"label": "Audio Data", "description": "Provides details about audio used in the video (TikTok only)."}, "shorts_format": {"label": "Shorts Format", "description": "Specifies whether a video is a shorts format video."}}}, "sort": {"type": "object", "description": "Define how videos are sorted. By default videos are sorted by views in descending order.", "properties": {"sort": {"type": "string", "description": "A metric to sort videos by. Defaults to \"views\" if not specified.", "x-component": "select", "x-options": {"views": {"label": "Views", "description": "Total lifetime views, as measured by the platform"}, "engagements": {"label": "Engagements", "description": "Total native actions(e.g. likes, comments, shares)"}, "upload_date": {"label": "Video Upload Date", "description": null}, "duration": {"label": "Duration", "description": "Video duration in seconds"}, "er1": {"label": "ER1", "description": "Engagement Rate in first 30 days indexed against a platform average (1.0x is average)"}, "er2": {"label": "ER2", "description": "Day 2 Engagement Rating"}, "er3": {"label": "ER3", "description": "Day 3 Engagement Rating"}, "er7": {"label": "ER7", "description": "Day 7 Engagement Rating"}, "er30": {"label": "ER30", "description": "Day 30 Engagement Rating"}, "v1": {"label": "V1", "description": "Views in the first day"}, "v2": {"label": "V2", "description": "Views in the first 2 days"}, "v3": {"label": "V3", "description": "Views in the first 3 days"}, "v7": {"label": "V7", "description": "Views in the first 7 days"}, "v30": {"label": "V30", "description": "Views in the first 30 days"}, "likes": {"label": "Likes", "description": "Total lifetime likes on the video or video post."}, "comments": {"label": "Comments", "description": "Total lifetime comments on the video or video post."}, "shares": {"label": "Facebook Shares", "description": "Total lifetime Facebook shares on the video or video post."}, "tweets": {"label": "Twitter re-tweets", "description": "Total lifetime re-tweets of the Twitter post"}, "loves": {"label": "Facebook \"Loves\" reactions", "description": "Total lifetime \"loves\" reactions."}, "hahas": {"label": "Facebook \"hahas\" reactions", "description": "Total lifetime \"hahas\" reactions."}, "wows": {"label": "Facebook \"wows\" reactions", "description": "Total lifetime \"wows\" reactions."}, "sads": {"label": "Facebook \"sads\" reactions", "description": "Total lifetime \"sads\" reactions."}, "angrys": {"label": "Facebook \"angrys\" reactions", "description": "Total lifetime \"angrys\" reactions."}, "views_gain": {"label": "Views gain", "description": "Views gained over <b>sort_date_range</b> period"}, "engagements_gain": {"label": "Engagements gain", "description": "Engagements gained over <b>sort_date_range</b> period"}}}, "sort_reverse": {"type": "boolean", "description": "Specifies whether to sort search results in ascending (sort_reverse=False) or descending (sort_reverse=True) order. This parameter will default to ascending (sort_reverse=False) if not specified."}, "sort_date_range": {"type": "object", "x-component": "dateRange", "description": "Defines a date range to get trends data for.", "properties": {"min": {"type": "string", "description": "The minimum date to be included as part of a range of dates in \"YYYY-MM-DD\"", "x-component": "date"}, "max": {"type": "string", "description": "The maximum date to be included as part of a range of dates in \"YYYY-MM-DD\" format.", "x-component": "date"}}, "x-options": [{"label": "Last day", "value": "last_day"}, {"label": "Last week", "value": "last_7"}, {"label": "Last 30 days", "value": "last_30"}, {"label": "Last 90 days", "value": "last_90"}, {"label": "Last year", "value": "last_1_y"}, {"label": "Last two years", "value": "last_2_y"}, {"label": "Last three years", "value": "last_3_y"}, {"label": "All time", "value": "all_time"}, {"label": "Custom Date Range", "value": {"handler": "custom"}}]}}}, "scroll": {"type": "object", "description": "A JSON string representation of the scroll window to use. This should only be set after an initial query has been performed in order to page through results.", "properties": {"scroll_token": {"type": "string", "description": "A unique id associated with the current query for which results are being retrieved. Note that the scroll token will expire if not used within 1 minute."}, "scroll_size": {"type": "integer", "description": "The maximum number of results to include for each window of results. Subsequent requests to creator.search or video.search will retrieve another ScrollWindow.scroll_size results. This parameter will default to 50 if not specified. The maximum scroll window size is 200."}}}}}}}}, "responses": {"200": {"description": "A JSON array of videos", "headers": {"Tubular-RateLimit-Overall-Limit": {"description": "The overall rate limit is 60 requests per minute. This rate limit applies to any combination of API methods that are called within a trailing 1-minute timeframe.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Overall-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Limit": {"description": "The concurrency rate limit is set to 1. This means that no more than a single request can be made at a time (i.e., in parallel). Attempting to issue a video.search request while a video.facets request is still running, for example will cause the video.search request to return a rate_limited error.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Remaining": {"description": "Number of concurrent requests available for use.", "schema": {"type": "integer"}}, "Tubular-Quota-Rows-Consumed": {"description": "Number of rows consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Consumed": {"description": "Number of quota units consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Limit": {"description": "Total quota units available for the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Remaining": {"description": "Number of quota units remaining in the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Expires-After": {"description": "Date and time when the current quota period ends.", "schema": {"type": "string", "format": "date-time"}}, "Tubular-RateLimit-UniqueVideoLimit-Limit": {"description": "Defines the total number of unique videos a client can retrieve in the current month.", "schema": {"type": "integer"}}, "Tubular-RateLimit-UniqueVideoLimit-Remaining": {"description": "A number of unique creators left in this month.", "schema": {"type": "integer"}}, "Tubular-RateLimit-UniqueVideoLimit-ExpiresAfter": {"description": "Specifies the date when the quota resets. Usually a beginning of each month.", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"type": "object", "properties": {"ok": {"type": "boolean", "description": "Standard API response for success/failure."}, "total": {"type": "integer", "description": "The total number of videos found"}, "video_ids": {"type": "array", "description": "A list of video IDs objects", "items": {"type": "object", "properties": {"platform": {"type": "string", "description": "A platform the video is published on"}, "id": {"type": "string", "description": "A video id within the platform"}}}}, "videos": {"type": "array", "description": "A list of videos objects.", "items": {"type": "object", "properties": {"views_gain": {"type": "integer", "description": "Views gained for a requested period. This attribute is populated only when sorting by \"views_gain\""}, "engagements_gain": {"type": "integer", "description": "Engagements gained for a requested period. This attribute is populated only when sorting by \"engagements_gain\""}, "video_id": {"type": "object", "description": "Video ID object representing unique video identifier across all platforms.", "properties": {"platform": {"type": "string", "description": "The social platform for the video."}, "id": {"type": "string", "description": "Video identifier for a particular video. A video id is guaranteed to be globally unique (i.e., no two videos will ever use the same id). You can use a video.details query to gather more information about a specific video."}}}, "title": {"type": "string", "description": "The title of the video."}, "description": {"type": "string", "description": "The description of the video."}, "keywords": {"type": "array", "description": "The keywords of the video if available on a platform.", "items": {"type": "string"}}, "hashtags": {"type": "array", "description": "A list of hashtags added to the video description in the form of", "items": {"type": "string"}}, "mentions": {"type": "array", "description": "A list of mentions in the video taken from the description in the form of @someone.", "items": {"type": "string"}}, "audio": {"type": "object", "description": "Audio used in the video (TikTok only).", "properties": {"id": {"type": "string", "description": "Unique song identifier"}, "title": {"type": "string", "description": "Song/audio title"}, "author": {"type": "string", "description": "Song/audio author name"}, "is_original": {"type": "boolean", "description": "Whether a sound is original"}}}, "platform": {"type": "string", "description": "The social platform where the video was published."}, "publish_date": {"type": "string", "x-component": "date", "description": "Date in YYYY-MM-DD format when a video was published"}, "publish_timestamp": {"type": "string", "x-component": "date-time", "description": "Timestamp in YYYY-MM-DD HH:MM:SS format when a video was published"}, "publisher": {"type": "object", "description": "JSON object representing information about the creator that published the video.", "properties": {"creator_id": {"type": "string", "description": "Publisher creator ID"}, "creator_name": {"type": "string", "description": "Publisher name"}, "creator_type": {"type": "string", "description": "Publisher type"}, "creator_country": {"type": "string", "description": "Creator country"}, "creator_genre": {"type": "integer", "description": "Creator genre"}}}, "thumbnail_url": {"type": "string", "description": "The URL of the thumbnail image for this video."}, "video_url": {"type": "string", "description": "The URL of the original video on the platform."}, "duration": {"type": "integer", "description": "Video duration in seconds"}, "youtube_category": {"type": "string", "description": "The YouTube category used when uploading the video. Note that this field is specific to YouTube videos and will otherwise be empty."}, "video_was_live": {"type": "boolean", "description": "Specifies whether a video was lived streamed."}, "video_is_reel": {"type": "boolean", "description": "Specifies whether a video is Instagram Reel."}, "video_is_360": {"type": "boolean", "description": "Specifies whether a video is in 360 (spherical) format."}, "video_is_made_for_kids": {"type": "boolean", "description": "Specifies whether a video is marked as kids content."}, "views": {"type": "integer", "description": "Total number of video views. Note that this value will be null for videos from certain platforms such as Twitter and Twitch, for which Tubular currently does not collect views."}, "engagements": {"type": "object", "description": "Total number of video engagements.", "properties": {"total": {"type": "integer", "description": "Total number of video engagements."}, "breakdown": {"type": "array", "description": "Breakdown of engagements by their type", "items": {"type": "object", "properties": {"platform": {"type": "string"}, "total": {"type": "integer"}, "likes": {"type": "integer"}, "shares": {"type": "integer"}, "comments": {"type": "integer"}, "tweets": {"type": "integer"}, "favorites": {"type": "integer"}, "hahas": {"type": "integer"}, "wows": {"type": "integer"}, "loves": {"type": "integer"}, "sads": {"type": "integer"}, "angrys": {"type": "integer"}}}}}}, "language": {"type": "string", "description": "ISO 639-1 two-letter language code that specifies the language used for this video."}, "topics": {"type": "object", "description": "A list of JSON objects representing different topics associated with this video.", "properties": {"topic_id": {"type": "string", "description": "Unique topic identifier"}, "topic_name": {"type": "string", "description": "Topic name"}}}, "categories": {"type": "object", "description": "A list of JSON objects representing different categories associated with this video.", "properties": {"category_name": {"type": "string", "description": "Name of the category associated with the video."}}}, "tvr": {"type": "object", "description": "JSON object representing the Tubular Video Ratings associated with this video. Note that this object will be null for videos from certain platforms such as Twitter and Twitch, for which Tubular currently does not collect views.", "properties": {"v1": {"type": "integer", "description": "The total views of a video during its first day"}, "v2": {"type": "integer", "description": "The total views of a video during its first 2 days"}, "v3": {"type": "integer", "description": "The total views of a video during its first 3 days"}, "v7": {"type": "integer", "description": "The total views of a video during its first 7 days"}, "v30": {"type": "integer", "description": "The total views of a video during its first 30 days"}, "e1": {"type": "integer", "description": "The total engagements of a video during its first day"}, "e2": {"type": "integer", "description": "The total engagements of a video during its first 2 days"}, "e3": {"type": "integer", "description": "The total engagements of a video during its first 3 days"}, "e7": {"type": "integer", "description": "The total engagements of a video during its first 7 days"}, "e30": {"type": "integer", "description": "The total engagements of a video during its first 30 days"}, "er1": {"type": "number", "format": "double", "x-component": "double", "description": "The first day [engagements / views] on a video compared to a platform average baseline"}, "er2": {"type": "number", "format": "double", "x-component": "double", "description": "The first 2 day [engagements / views] on a video compared to a platform average baseline"}, "er3": {"type": "number", "format": "double", "x-component": "double", "description": "The first 3 day [engagements / views] on a video compared to a platform average baseline"}, "er7": {"type": "number", "format": "double", "x-component": "double", "description": "The first 7 day [engagements / views] on a video compared to a platform average baseline"}, "er30": {"type": "number", "format": "double", "x-component": "double", "description": "The first 30 day [engagements / views] on a video compared to a platform average baseline"}}}}}}}}}}}, "429": {"description": "The query is quota or rate-limited.", "headers": {"Tubular-RateLimit-Overall-Limit": {"description": "The overall rate limit is 60 requests per minute. This rate limit applies to any combination of API methods that are called within a trailing 1-minute timeframe.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Overall-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Limit": {"description": "The concurrency rate limit is set to 1. This means that no more than a single request can be made at a time (i.e., in parallel). Attempting to issue a video.search request while a video.facets request is still running, for example will cause the video.search request to return a rate_limited error.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Remaining": {"description": "Number of concurrent requests available for use.", "schema": {"type": "integer"}}, "Tubular-Quota-Rows-Consumed": {"description": "Number of rows consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Consumed": {"description": "Number of quota units consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Limit": {"description": "Total quota units available for the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Remaining": {"description": "Number of quota units remaining in the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Expires-After": {"description": "Date and time when the current quota period ends.", "schema": {"type": "string", "format": "date-time"}}, "Tubular-RateLimit-UniqueVideoLimit-Limit": {"description": "Defines the total number of unique videos a client can retrieve in the current month.", "schema": {"type": "integer"}}, "Tubular-RateLimit-UniqueVideoLimit-Remaining": {"description": "A number of unique creators left in this month.", "schema": {"type": "integer"}}, "Tubular-RateLimit-UniqueVideoLimit-ExpiresAfter": {"description": "Specifies the date when the quota resets. Usually a beginning of each month.", "schema": {"type": "integer"}}}}}}}, "/video.trends_summary": {"x-requires": ["api_intelligence"], "x-group": ["data", "video"], "post": {"summary": "Get aggregated views, engagements, uploads over time for a videos matching the search criteria.", "description": "Get aggregated views, engagements, uploads over time for a videos matching the search criteria.", "parameters": [{"in": "header", "description": "Tubular API key.", "name": "Api-Key", "schema": {"type": "string"}}], "requestBody": {"content": {"application/json": {"schema": {"type": "object", "required": ["query", "date_range", "metric"], "properties": {"query": {"type": "object", "description": "Defines search criteria that combines include and exclude filters.", "properties": {"savedsearch_id": {"type": "integer", "x-component": "select", "description": "Video saved search id", "x-source": "qb/getVideoSavedSearches"}, "include_filter": {"type": "object", "description": "A video filter to be included by the query. Defaults to include everything if not specified.", "properties": {"search": {"type": "string", "description": "The search text string to be included in the filter for searching across video titles. This string may include optional boolean search operators as described by the Help Center. Defaults to empty string if not specified.", "x-hint": "Use AND and OR operators", "x-placeholder": "I'm a placeholder"}, "search_description": {"type": "boolean", "description": "Controls whether to search the video descriptions when providing a search string parameter. Defaults to false if not specified."}, "search_keywords": {"type": "boolean", "description": "Controls whether to search the video keywords when providing a search string parameter. Defaults to false if not specified."}, "search_topics": {"type": "boolean", "description": "Controls whether to search the video topics when providing a search string parameter. Defaults to true if not specified."}, "video_gids": {"type": "array", "x-component": "select", "x-add": true, "description": "A list of specific videos to fetch. Each video is represent in the form of GID which consists of a platform prefix and original video ID. The prefixes are <ul> <li><b>ytv_</b> - YouTube</li> <li><b>fbv_</b> - Facebook</li> <li><b>igv_</b> - Instagram</li> <li><b>twv_</b> - Twitter</li> <li><b>tkv_</b> - TikTok</li> <li><b>ttv_</b> - Twitch</li> </ul> For example, a gid for Gangnam Style video would be <b>ytv_9bZkp7q19f0</b>", "items": {"type": "string"}}, "video_platforms": {"type": "array", "x-component": "select", "description": "An array of social platforms to use in the filter.", "x-options": {"youtube": "YouTube", "facebook": "Facebook", "instagram": "Instagram", "twitch": "Twitch", "tiktok": "TikTok"}, "items": {"type": "string"}}, "video_upload_date": {"type": "object", "x-component": "dateRange", "description": "Applies a date range limit to the date a video was uploaded. Note that this parameter has a large impact on query response times. In general, <b>the larger</b> the time span the more time the query will take to complete.\nInclude filters will default to a minimum upload date of 'last_90' if not specified. Exclude filters must specify a minimum upload date when providing the video_upload_date parameter. Due to performance reasons, this date range cannot span beyond the value allowed by your plan. To query a larger date range, you will need to issue multiple queries each with a different range and combine results.", "properties": {"min": {"type": "string", "description": "The minimum date to be included as part of a range of dates in \"YYYY-MM-DD\"", "x-component": "date"}, "max": {"type": "string", "description": "The maximum date to be included as part of a range of dates in \"YYYY-MM-DD\" format.", "x-component": "date"}}, "x-options": [{"label": "Last day", "value": "last_day"}, {"label": "Last week", "value": "last_7"}, {"label": "Last 30 days", "value": "last_30"}, {"label": "Last 90 days", "value": "last_90"}, {"label": "Last year", "value": "last_1_y"}, {"label": "Last two years", "value": "last_2_y"}, {"label": "Last three years", "value": "last_3_y"}, {"label": "All time", "value": "all_time"}, {"label": "Custom Date Range", "value": {"handler": "custom"}}]}, "video_duration": {"type": "object", "x-component": "integerRange", "description": "Applies a duration limit in seconds to use in the filter.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "video_was_live": {"type": "boolean", "description": "Specifies whether to include videos that were lived streamed. Ignored if not specified."}, "video_is_made_for_kids": {"type": "boolean", "description": "Specifies whether to include YouTube videos that were marked as \"Made for Kids\". Ignored if not specified."}, "video_is_reel": {"type": "boolean", "description": "Specifies whether to include Instagram Reel videos. Ignored if not specified."}, "video_is_360": {"type": "boolean", "description": "Specifies whether to include videos in the 360 (spherical) format. Ignored if not specified."}, "video_is_noteworthy": {"type": "boolean", "description": "Experimental feature. Specifies whether to include videos that get more views than expected given the creator's followers count and do not primarily get views from advertising. Ignored if not specified."}, "video_languages": {"type": "array", "description": "Specifies the language of the video to use in the filter. Note that available languages are currently not obtainable via a VideoFacets query. Language strings are represented as <a href=\"https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes\">ISO 639-1</a> two-letter language codes. Defaults to all languages if not specified.", "items": {"type": "string"}, "x-component": "select", "x-autocomplete": "qb/getLanguages"}, "video_list": {"type": "integer", "description": "A video custom list identifier to use in the filter. A video list represents a custom list of videos. These custom lists can be created and modified programmatically.\nSee the Custom List Methods section of the API documentation for more details. Available video lists can be obtained via the custom_list.enumerate method. Defaults to not include a video list.", "x-component": "select", "x-source": "qb/getVideoLists"}, "video_lists": {"type": "array", "description": "One or more video custom list identifiers to use in the filter. A video list represents a custom list of videos. These custom lists can be created and modified programmatically. See the Custom List Methods section of the API documentation for more details. Available video lists can be obtained via the custom_list.enumerate method. Defaults to not include a video list.", "x-component": "select", "x-source": "qb/getVideoLists", "items": {"type": "integer"}}, "video_categories": {"type": "array", "description": "Specifies a list of category names to use in the filtering. Defaults to all categories if not specified. Currently we support categories for Youtube and Facebook platforms only.", "items": {"type": "string"}, "x-component": "select", "x-autocomplete": "qb/searchVideoCategories"}, "video_entities": {"type": "array", "x-component": "select", "description": "Specifies a list of video topic identifiers to use in the filters. Defaults to all topics if not specified.", "items": {"type": "integer"}, "x-autocomplete": "qb/searchVideoTopics", "x-add": true}, "video_views": {"type": "object", "x-component": "integerRange", "description": "Applies a view limit (total number of views) to use in the filter. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "video_engagements": {"type": "object", "x-component": "integerRange", "description": "Applies a cross-platform enagement limit to use in the filter. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "hashtags": {"type": "array", "description": "Show only videos that have one or more", "x-component": "select", "x-add": true, "items": {"type": "string"}}, "mentions": {"type": "array", "description": "Show only videos that have one or more @mention in the description.", "x-component": "select", "x-add": true, "items": {"type": "string"}}, "challenges": {"type": "array", "description": "Show only videos that are part of a given challenge (TikTok only).", "x-component": "select", "x-add": true, "items": {"type": "string"}}, "audio_ids": {"type": "array", "description": "Show only videos that use one or more audio IDs (TikTok only).", "x-component": "select", "x-add": true, "items": {"type": "string"}}, "audio_titles": {"type": "array", "description": "Show only videos that use one or more audio title (TikTok only).", "x-component": "select", "x-add": true, "x-autocomplete": "qb/searchAudioTitles", "items": {"type": "string"}}, "audio_authors": {"type": "array", "description": "Show only videos that use audio of one or more audio authors (TikTok only).", "x-component": "select", "x-add": true, "x-autocomplete": "qb/searchAudioAuthors", "items": {"type": "string"}}, "audio_is_original": {"type": "boolean", "description": "Show only videos that use original audio (TikTok only)."}, "creator_types": {"type": "array", "description": "An array of creator types to use in the filter.", "x-component": "select", "x-options": {"influencer": "Influencer", "brand": "Brand", "media company": "Media Company", "aggregator": "Aggregator"}, "items": {"type": "string"}}, "creator_industries": {"type": "array", "description": "An array of creator industry identifiers to use in the filter. Defaults to all creator industries if not specified. Relevant for Brands.", "x-component": "select", "x-options": {"1": "Technology", "2": "Travel & Leisure", "3": "Music", "4": "CPG", "5": "Automotive", "6": "Financial & Insurance", "7": "Toys & Board Games", "8": "Media", "9": "Retail", "10": "Logistics & Heavy Industry", "11": "Other", "12": "Apparel & Accessories", "13": "Beverages", "14": "Personal Care & Health", "15": "Education", "16": "Public Service & Nonprofit", "17": "Food", "19": "Telecom", "20": "Pets", "21": "Sports Teams & Leagues", "22": "Gaming", "23": "Energy", "25": "Electronics", "27": "Broadcast, Cable, Radio, Film", "28": "Digital First Media", "29": "Magazine & Newspaper", "30": "Beauty"}, "items": {"type": "integer"}}, "creator_properties": {"type": "array", "x-component": "select", "description": "An array of creator property identifiers to use in the filter. Available creator properties can be obtained via a VideoFacets query. Defaults to all creator properties if not specified.", "x-autocomplete": "qb/searchProperties", "items": {"type": "integer"}}, "creator_list": {"type": "integer", "description": "A creator custom list identifier to use in the filter. A creator list represents a custom list of creators. These custom lists can be created and modified programmatically. See the Custom List section of the API documentation for more details. Available creator lists can be obtained via the custom_list.enumerate method. Defaults to not include a creator list.", "x-component": "select", "x-source": "qb/getCreatorLists"}, "creator_lists": {"type": "array", "description": "One or more creator custom list identifiers to use in the filter. A creator list represents a custom list of creators. These custom lists can be created and modified programmatically. See the Custom List section of the API documentation for more details. Available creator lists can be obtained via the custom_list.enumerate method. Defaults to not include a creator list.", "x-component": "select", "x-source": "qb/getCreatorLists", "items": {"type": "integer"}}, "creators": {"type": "array", "x-component": "select", "description": "An array of creator identifiers to use in the filter. Available creator identifiers can be obtained via the VideoFacets method or by searching for a particular creator via the CreatorSearch method. Defaults to all creators.", "x-add": true, "x-autocomplete": "qb/searchCreators", "items": {"type": "string"}}, "creator_accounts": {"type": "array", "x-component": "select", "description": "An array of creator social account identifiers to use in the filter. Available creator account identifiers can be obtained via the VideoFacets method or by the list of social accounts associated with a particular creator obtained via the CreatorDetails query. Defaults to all creator accounts if not specified.", "items": {"type": "string"}, "x-add": true}, "creator_account_followers": {"type": "object", "x-component": "integerRange", "description": "Applies a range limit to the follower count for the creator's social account that published a video (i.e., only videos whose follower counts fall within the range will be included). Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "creator_account_countries": {"type": "array", "description": "Specifies the countries associated with the creator account when limiting videos (e.g., only videos whose account are associated with the United States and France). Unlike creator_countries, this filter is applied to the country value set by the original platform. Country strings are represented as two-letter ISO 3166-1 alpha-2 codes. Defaults to all countries if not specified.", "items": {"type": "string"}, "x-component": "select", "x-autocomplete": "qb/getCountries"}, "creator_account_categories": {"type": "array", "description": "Specifies the categories associated with the creator account when limiting videos. Unlike video_categories, this filter is applied to the category value set by the original platform.", "items": {"type": "integer"}, "x-component": "select", "x-options": {"1": "Film & Animation", "2": "Autos & Vehicles", "10": "Music", "15": "Pets & Animals", "17": "Sports", "19": "Travel & Events", "20": "Gaming", "22": "People & Blogs", "23": "Comedy", "24": "Entertainment", "25": "News & Politics", "26": "Howto & Style", "27": "Education", "28": "Science & Technology", "29": "Nonprofits & Activism"}}, "creator_genres": {"type": "array", "description": "An array of content genre identifiers to use in the filter. Available content genre identifiers can be obtained via a VideoFacets query. Defaults to all content genres if not specified.", "x-component": "select", "x-options": {"2": "Travel", "3": "Music & Dance", "4": "Sports", "5": "Animals & Pets", "7": "People & Blogs", "9": "Cars, Trucks & Racing", "11": "Business", "13": "Kids Entertainment & Animation", "14": "Education", "15": "Food & Drink", "16": "Fashion & Style", "19": "Health, Fitness & Self Help", "21": "Home & DIY", "22": "News & Politics", "23": "Beauty", "24": "Film & Movies", "27": "Gaming", "32": "Family & Parenting", "33": "Science & Tech", "36": "Entertainment", "37": "General Interest"}, "items": {"type": "integer"}}, "creator_facebook_watch": {"type": "boolean", "description": "Limits the creators to those that publish a show on Facebook watch. Defaults to include all if not specified. Value can only be true or unspecified."}, "creator_countries": {"type": "array", "description": "Specifies the countries associated with the creator's accounts when limiting videos (e.g., only videos whose accounts are associated with the United States and France). Available creator countries can be obtained via a VideoFacets query. Country strings are represented as two-letter ISO 3166-1 alpha-2 codes. Defaults to all countries if not specified.", "items": {"type": "string"}, "x-component": "select", "x-autocomplete": "qb/getCountries"}, "shorts_format": {"type": "array", "description": "Limits videos to platform-specific short formats.", "items": {"type": "string"}, "x-component": "select", "x-options": {"yt_shorts": "YouTube Shorts"}}}}, "exclude_filter": {"type": "object", "description": "A video filter to be excluded by the query. Defaults to exclude no videos if not specified.", "properties": {"search": {"type": "string", "description": "The search text string to be included in the filter for searching across video titles. This string may include optional boolean search operators as described by the Help Center. Defaults to empty string if not specified.", "x-hint": "Use AND and OR operators", "x-placeholder": "I'm a placeholder"}, "search_description": {"type": "boolean", "description": "Controls whether to search the video descriptions when providing a search string parameter. Defaults to false if not specified."}, "search_keywords": {"type": "boolean", "description": "Controls whether to search the video keywords when providing a search string parameter. Defaults to false if not specified."}, "search_topics": {"type": "boolean", "description": "Controls whether to search the video topics when providing a search string parameter. Defaults to true if not specified."}, "video_gids": {"type": "array", "x-component": "select", "x-add": true, "description": "A list of specific videos to fetch. Each video is represent in the form of GID which consists of a platform prefix and original video ID. The prefixes are <ul> <li><b>ytv_</b> - YouTube</li> <li><b>fbv_</b> - Facebook</li> <li><b>igv_</b> - Instagram</li> <li><b>twv_</b> - Twitter</li> <li><b>tkv_</b> - TikTok</li> <li><b>ttv_</b> - Twitch</li> </ul> For example, a gid for Gangnam Style video would be <b>ytv_9bZkp7q19f0</b>", "items": {"type": "string"}}, "video_platforms": {"type": "array", "x-component": "select", "description": "An array of social platforms to use in the filter.", "x-options": {"youtube": "YouTube", "facebook": "Facebook", "instagram": "Instagram", "twitch": "Twitch", "tiktok": "TikTok"}, "items": {"type": "string"}}, "video_upload_date": {"type": "object", "x-component": "dateRange", "description": "Applies a date range limit to the date a video was uploaded. Note that this parameter has a large impact on query response times. In general, <b>the larger</b> the time span the more time the query will take to complete.\nInclude filters will default to a minimum upload date of 'last_90' if not specified. Exclude filters must specify a minimum upload date when providing the video_upload_date parameter. Due to performance reasons, this date range cannot span beyond the value allowed by your plan. To query a larger date range, you will need to issue multiple queries each with a different range and combine results.", "properties": {"min": {"type": "string", "description": "The minimum date to be included as part of a range of dates in \"YYYY-MM-DD\"", "x-component": "date"}, "max": {"type": "string", "description": "The maximum date to be included as part of a range of dates in \"YYYY-MM-DD\" format.", "x-component": "date"}}, "x-options": [{"label": "Last day", "value": "last_day"}, {"label": "Last week", "value": "last_7"}, {"label": "Last 30 days", "value": "last_30"}, {"label": "Last 90 days", "value": "last_90"}, {"label": "Last year", "value": "last_1_y"}, {"label": "Last two years", "value": "last_2_y"}, {"label": "Last three years", "value": "last_3_y"}, {"label": "All time", "value": "all_time"}, {"label": "Custom Date Range", "value": {"handler": "custom"}}]}, "video_duration": {"type": "object", "x-component": "integerRange", "description": "Applies a duration limit in seconds to use in the filter.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "video_was_live": {"type": "boolean", "description": "Specifies whether to include videos that were lived streamed. Ignored if not specified."}, "video_is_made_for_kids": {"type": "boolean", "description": "Specifies whether to include YouTube videos that were marked as \"Made for Kids\". Ignored if not specified."}, "video_is_reel": {"type": "boolean", "description": "Specifies whether to include Instagram Reel videos. Ignored if not specified."}, "video_is_360": {"type": "boolean", "description": "Specifies whether to include videos in the 360 (spherical) format. Ignored if not specified."}, "video_is_noteworthy": {"type": "boolean", "description": "Experimental feature. Specifies whether to include videos that get more views than expected given the creator's followers count and do not primarily get views from advertising. Ignored if not specified."}, "video_languages": {"type": "array", "description": "Specifies the language of the video to use in the filter. Note that available languages are currently not obtainable via a VideoFacets query. Language strings are represented as <a href=\"https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes\">ISO 639-1</a> two-letter language codes. Defaults to all languages if not specified.", "items": {"type": "string"}, "x-component": "select", "x-autocomplete": "qb/getLanguages"}, "video_list": {"type": "integer", "description": "A video custom list identifier to use in the filter. A video list represents a custom list of videos. These custom lists can be created and modified programmatically.\nSee the Custom List Methods section of the API documentation for more details. Available video lists can be obtained via the custom_list.enumerate method. Defaults to not include a video list.", "x-component": "select", "x-source": "qb/getVideoLists"}, "video_lists": {"type": "array", "description": "One or more video custom list identifiers to use in the filter. A video list represents a custom list of videos. These custom lists can be created and modified programmatically. See the Custom List Methods section of the API documentation for more details. Available video lists can be obtained via the custom_list.enumerate method. Defaults to not include a video list.", "x-component": "select", "x-source": "qb/getVideoLists", "items": {"type": "integer"}}, "video_categories": {"type": "array", "description": "Specifies a list of category names to use in the filtering. Defaults to all categories if not specified. Currently we support categories for Youtube and Facebook platforms only.", "items": {"type": "string"}, "x-component": "select", "x-autocomplete": "qb/searchVideoCategories"}, "video_entities": {"type": "array", "x-component": "select", "description": "Specifies a list of video topic identifiers to use in the filters. Defaults to all topics if not specified.", "items": {"type": "integer"}, "x-autocomplete": "qb/searchVideoTopics", "x-add": true}, "video_views": {"type": "object", "x-component": "integerRange", "description": "Applies a view limit (total number of views) to use in the filter. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "video_engagements": {"type": "object", "x-component": "integerRange", "description": "Applies a cross-platform enagement limit to use in the filter. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "hashtags": {"type": "array", "description": "Show only videos that have one or more", "x-component": "select", "x-add": true, "items": {"type": "string"}}, "mentions": {"type": "array", "description": "Show only videos that have one or more @mention in the description.", "x-component": "select", "x-add": true, "items": {"type": "string"}}, "challenges": {"type": "array", "description": "Show only videos that are part of a given challenge (TikTok only).", "x-component": "select", "x-add": true, "items": {"type": "string"}}, "audio_ids": {"type": "array", "description": "Show only videos that use one or more audio IDs (TikTok only).", "x-component": "select", "x-add": true, "items": {"type": "string"}}, "audio_titles": {"type": "array", "description": "Show only videos that use one or more audio title (TikTok only).", "x-component": "select", "x-add": true, "x-autocomplete": "qb/searchAudioTitles", "items": {"type": "string"}}, "audio_authors": {"type": "array", "description": "Show only videos that use audio of one or more audio authors (TikTok only).", "x-component": "select", "x-add": true, "x-autocomplete": "qb/searchAudioAuthors", "items": {"type": "string"}}, "audio_is_original": {"type": "boolean", "description": "Show only videos that use original audio (TikTok only)."}, "creator_types": {"type": "array", "description": "An array of creator types to use in the filter.", "x-component": "select", "x-options": {"influencer": "Influencer", "brand": "Brand", "media company": "Media Company", "aggregator": "Aggregator"}, "items": {"type": "string"}}, "creator_industries": {"type": "array", "description": "An array of creator industry identifiers to use in the filter. Defaults to all creator industries if not specified. Relevant for Brands.", "x-component": "select", "x-options": {"1": "Technology", "2": "Travel & Leisure", "3": "Music", "4": "CPG", "5": "Automotive", "6": "Financial & Insurance", "7": "Toys & Board Games", "8": "Media", "9": "Retail", "10": "Logistics & Heavy Industry", "11": "Other", "12": "Apparel & Accessories", "13": "Beverages", "14": "Personal Care & Health", "15": "Education", "16": "Public Service & Nonprofit", "17": "Food", "19": "Telecom", "20": "Pets", "21": "Sports Teams & Leagues", "22": "Gaming", "23": "Energy", "25": "Electronics", "27": "Broadcast, Cable, Radio, Film", "28": "Digital First Media", "29": "Magazine & Newspaper", "30": "Beauty"}, "items": {"type": "integer"}}, "creator_properties": {"type": "array", "x-component": "select", "description": "An array of creator property identifiers to use in the filter. Available creator properties can be obtained via a VideoFacets query. Defaults to all creator properties if not specified.", "x-autocomplete": "qb/searchProperties", "items": {"type": "integer"}}, "creator_list": {"type": "integer", "description": "A creator custom list identifier to use in the filter. A creator list represents a custom list of creators. These custom lists can be created and modified programmatically. See the Custom List section of the API documentation for more details. Available creator lists can be obtained via the custom_list.enumerate method. Defaults to not include a creator list.", "x-component": "select", "x-source": "qb/getCreatorLists"}, "creator_lists": {"type": "array", "description": "One or more creator custom list identifiers to use in the filter. A creator list represents a custom list of creators. These custom lists can be created and modified programmatically. See the Custom List section of the API documentation for more details. Available creator lists can be obtained via the custom_list.enumerate method. Defaults to not include a creator list.", "x-component": "select", "x-source": "qb/getCreatorLists", "items": {"type": "integer"}}, "creators": {"type": "array", "x-component": "select", "description": "An array of creator identifiers to use in the filter. Available creator identifiers can be obtained via the VideoFacets method or by searching for a particular creator via the CreatorSearch method. Defaults to all creators.", "x-add": true, "x-autocomplete": "qb/searchCreators", "items": {"type": "string"}}, "creator_accounts": {"type": "array", "x-component": "select", "description": "An array of creator social account identifiers to use in the filter. Available creator account identifiers can be obtained via the VideoFacets method or by the list of social accounts associated with a particular creator obtained via the CreatorDetails query. Defaults to all creator accounts if not specified.", "items": {"type": "string"}, "x-add": true}, "creator_account_followers": {"type": "object", "x-component": "integerRange", "description": "Applies a range limit to the follower count for the creator's social account that published a video (i.e., only videos whose follower counts fall within the range will be included). Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "creator_account_countries": {"type": "array", "description": "Specifies the countries associated with the creator account when limiting videos (e.g., only videos whose account are associated with the United States and France). Unlike creator_countries, this filter is applied to the country value set by the original platform. Country strings are represented as two-letter ISO 3166-1 alpha-2 codes. Defaults to all countries if not specified.", "items": {"type": "string"}, "x-component": "select", "x-autocomplete": "qb/getCountries"}, "creator_account_categories": {"type": "array", "description": "Specifies the categories associated with the creator account when limiting videos. Unlike video_categories, this filter is applied to the category value set by the original platform.", "items": {"type": "integer"}, "x-component": "select", "x-options": {"1": "Film & Animation", "2": "Autos & Vehicles", "10": "Music", "15": "Pets & Animals", "17": "Sports", "19": "Travel & Events", "20": "Gaming", "22": "People & Blogs", "23": "Comedy", "24": "Entertainment", "25": "News & Politics", "26": "Howto & Style", "27": "Education", "28": "Science & Technology", "29": "Nonprofits & Activism"}}, "creator_genres": {"type": "array", "description": "An array of content genre identifiers to use in the filter. Available content genre identifiers can be obtained via a VideoFacets query. Defaults to all content genres if not specified.", "x-component": "select", "x-options": {"2": "Travel", "3": "Music & Dance", "4": "Sports", "5": "Animals & Pets", "7": "People & Blogs", "9": "Cars, Trucks & Racing", "11": "Business", "13": "Kids Entertainment & Animation", "14": "Education", "15": "Food & Drink", "16": "Fashion & Style", "19": "Health, Fitness & Self Help", "21": "Home & DIY", "22": "News & Politics", "23": "Beauty", "24": "Film & Movies", "27": "Gaming", "32": "Family & Parenting", "33": "Science & Tech", "36": "Entertainment", "37": "General Interest"}, "items": {"type": "integer"}}, "creator_facebook_watch": {"type": "boolean", "description": "Limits the creators to those that publish a show on Facebook watch. Defaults to include all if not specified. Value can only be true or unspecified."}, "creator_countries": {"type": "array", "description": "Specifies the countries associated with the creator's accounts when limiting videos (e.g., only videos whose accounts are associated with the United States and France). Available creator countries can be obtained via a VideoFacets query. Country strings are represented as two-letter ISO 3166-1 alpha-2 codes. Defaults to all countries if not specified.", "items": {"type": "string"}, "x-component": "select", "x-autocomplete": "qb/getCountries"}, "shorts_format": {"type": "array", "description": "Limits videos to platform-specific short formats.", "items": {"type": "string"}, "x-component": "select", "x-options": {"yt_shorts": "YouTube Shorts"}}}}}}, "metric": {"type": "string", "description": "Name of a metric for which the trends are calculated.", "x-component": "select", "x-options": {"views": {"label": "Views", "description": "Get trends by views"}, "engagements": {"label": "Engagements", "description": "Get trends by engagments(e.g. likes, comments, shares)"}}}, "time_bucket": {"type": "string", "description": "Specify a time quantity to group trends data by. A time series of trends data will be produced using this time quantity as the time increment. If not specified, the default time_bucket of days will be used.", "x-component": "select", "x-options": {"all": {"label": "All", "description": "All data is represented in a single bucket"}, "days": {"label": "Daily", "description": "Trends data provided in daily increments"}, "weeks": {"label": "Weekly", "description": "Trends data provided in weekly increments"}, "months": {"label": "Monthly", "description": "Trends data provided in monthly increments"}, "years": {"label": "Yearly", "description": "Trends data provided in yearly increments"}, "dayofweek": {"label": "Day of Week", "description": "Trends provided by the day of a week (Mon, Tue, ...)"}}}, "segmentation_attribute": {"type": "string", "x-component": "select", "description": "An attribute to segment the results by.", "x-options": {"platform": {"label": "Platform", "description": "Group videos by video platforms"}, "category": {"label": "Video Category", "description": "Group videos by video category."}, "entity": {"label": "Video Topic", "description": "Group videos by video topics"}, "language": {"label": "Language", "description": "Group videos by video languages"}, "duration": {"label": "Duration", "description": "Group videos by video duration buckets"}, "format": {"label": "Format", "description": "Group videos by video formats (live, 360 videos)"}, "dayofweek": {"label": "Day of Week", "description": "Group videos by video upload day of a week 0 - Monday, 1 - Tuesday, ... 6 - Sunday"}, "creator": {"label": "Creator", "description": "Group videos by creators"}, "creator_type": {"label": "Creator Type", "description": "Group videos by creator types (brands, media, etc.)"}, "creator_genre": {"label": "Creator Genre", "description": "Group videos by creator genres"}, "creator_country": {"label": "Creator Country", "description": "Group videos by creator countries"}, "creator_brand_industry": {"label": "Creator Brand Industry", "description": "Group videos by a creator brand industries"}, "creator_property": {"label": "Creator Property", "description": "Group videos by creator parent properties"}, "hashtag": {"label": "Hashtags", "description": "Group videos by hashtags mentioned in the video description"}, "mention": {"label": "Mentions", "description": "Group videos by mentions added to the video description"}, "audio_title": {"label": "Audio Title", "description": "Group videos by audio title used in the video (TikTok only)"}, "audio_author": {"label": "Audio Author", "description": "Group videos by audio authors whose sound is used in the video (TikTok only)"}}}, "segmentation_depth": {"type": "integer", "description": "Defines how many attributes to return when segmentation_attribute is specified. Default value is 10. An upper limit is defined in your plan."}, "date_range": {"type": "object", "x-component": "dateRange", "description": "Defines a date range to get trends data for.", "properties": {"min": {"type": "string", "description": "The minimum date to be included as part of a range of dates in \"YYYY-MM-DD\"", "x-component": "date"}, "max": {"type": "string", "description": "The maximum date to be included as part of a range of dates in \"YYYY-MM-DD\" format.", "x-component": "date"}}, "x-options": [{"label": "Last day", "value": "last_day"}, {"label": "Last week", "value": "last_7"}, {"label": "Last 30 days", "value": "last_30"}, {"label": "Last 90 days", "value": "last_90"}, {"label": "Last year", "value": "last_1_y"}, {"label": "Last two years", "value": "last_2_y"}, {"label": "Last three years", "value": "last_3_y"}, {"label": "All time", "value": "all_time"}, {"label": "Custom Date Range", "value": {"handler": "custom"}}]}}}}}}, "responses": {"200": {"description": "A JSON array of videos", "headers": {"Tubular-RateLimit-Overall-Limit": {"description": "The overall rate limit is 60 requests per minute. This rate limit applies to any combination of API methods that are called within a trailing 1-minute timeframe.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Overall-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Limit": {"description": "The concurrency rate limit is set to 1. This means that no more than a single request can be made at a time (i.e., in parallel). Attempting to issue a video.search request while a video.facets request is still running, for example will cause the video.search request to return a rate_limited error.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Remaining": {"description": "Number of concurrent requests available for use.", "schema": {"type": "integer"}}, "Tubular-Quota-Rows-Consumed": {"description": "Number of rows consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Consumed": {"description": "Number of quota units consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Limit": {"description": "Total quota units available for the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Remaining": {"description": "Number of quota units remaining in the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Expires-After": {"description": "Date and time when the current quota period ends.", "schema": {"type": "string", "format": "date-time"}}, "Tubular-RateLimit-FacetSummary-Limit": {"description": "All aggregated request for either creators or videos are inherently expensive. Because of this, Tubular places a limit of no more than 6 total facet and summary requests per minute.", "schema": {"type": "integer"}}, "Tubular-RateLimit-FacetSummary-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"type": "object", "properties": {"ok": {"type": "boolean", "description": "Standard API response for success/failure."}, "summary": {"type": "array", "description": "A list of dict-like objects depicting a by-attribute breakdown of trends statistics for the given query filter.", "items": {"type": "object", "properties": {"metric": {"type": "string", "description": "A metric name trends data is retrieved for."}, "value": {"type": "integer", "description": "Metric value for a given bucket."}, "time_bucket_value": {"type": "string", "description": "The time bucket value contains \"all\" if time bucket in the request is set to \"all\", otherwise it's an alias describing the time range of of the time bucket. \"YYYY-MM-DD\" - when time_bucket=days \"YYYY-MM\" - when time_bucket=months \"YYYY-WXX\" - when time_bucket=weeks where XX is the number of a year week \"YYYY\" - when time_bucket=years \"Mon/Tue/Wed...\" - when time_bucket=dayofweek"}, "start_date": {"type": "string", "format": "date", "description": "Start date of a time bucket period."}, "end_date": {"type": "string", "format": "date", "description": "End date of a time bucket period."}, "attribute_value": {"type": "string", "description": "The attribute value used for segmenting as specified in the query."}, "attribute_details": {"type": "object", "description": "The segmenting attribute details such as id and title.", "properties": {"id": {"type": "string", "description": "Id of an object used in segmentation."}, "title": {"type": "string", "description": "Title of an object used in segmentation."}}}}}}}}}}}, "429": {"description": "The query is quota or rate-limited.", "headers": {"Tubular-RateLimit-Overall-Limit": {"description": "The overall rate limit is 60 requests per minute. This rate limit applies to any combination of API methods that are called within a trailing 1-minute timeframe.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Overall-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Limit": {"description": "The concurrency rate limit is set to 1. This means that no more than a single request can be made at a time (i.e., in parallel). Attempting to issue a video.search request while a video.facets request is still running, for example will cause the video.search request to return a rate_limited error.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Remaining": {"description": "Number of concurrent requests available for use.", "schema": {"type": "integer"}}, "Tubular-Quota-Rows-Consumed": {"description": "Number of rows consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Consumed": {"description": "Number of quota units consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Limit": {"description": "Total quota units available for the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Remaining": {"description": "Number of quota units remaining in the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Expires-After": {"description": "Date and time when the current quota period ends.", "schema": {"type": "string", "format": "date-time"}}, "Tubular-RateLimit-FacetSummary-Limit": {"description": "All aggregated request for either creators or videos are inherently expensive. Because of this, Tubular places a limit of no more than 6 total facet and summary requests per minute.", "schema": {"type": "integer"}}, "Tubular-RateLimit-FacetSummary-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}}}}}}, "/video.trends_top": {"x-requires": ["api_intelligence"], "x-group": ["data", "video"], "post": {"summary": "Get top N videos that contributed the most views over a historical period of time.", "parameters": [{"in": "header", "description": "Tubular API key.", "name": "Api-Key", "schema": {"type": "string"}}], "requestBody": {"content": {"application/json": {"schema": {"type": "object", "required": ["query", "date_range", "metric"], "properties": {"query": {"type": "object", "description": "Defines search criteria that combines include and exclude filters.", "properties": {"savedsearch_id": {"type": "integer", "x-component": "select", "description": "Video saved search id", "x-source": "qb/getVideoSavedSearches"}, "include_filter": {"type": "object", "description": "A video filter to be included by the query. Defaults to include everything if not specified.", "properties": {"search": {"type": "string", "description": "The search text string to be included in the filter for searching across video titles. This string may include optional boolean search operators as described by the Help Center. Defaults to empty string if not specified.", "x-hint": "Use AND and OR operators", "x-placeholder": "I'm a placeholder"}, "search_description": {"type": "boolean", "description": "Controls whether to search the video descriptions when providing a search string parameter. Defaults to false if not specified."}, "search_keywords": {"type": "boolean", "description": "Controls whether to search the video keywords when providing a search string parameter. Defaults to false if not specified."}, "search_topics": {"type": "boolean", "description": "Controls whether to search the video topics when providing a search string parameter. Defaults to true if not specified."}, "video_gids": {"type": "array", "x-component": "select", "x-add": true, "description": "A list of specific videos to fetch. Each video is represent in the form of GID which consists of a platform prefix and original video ID. The prefixes are <ul> <li><b>ytv_</b> - YouTube</li> <li><b>fbv_</b> - Facebook</li> <li><b>igv_</b> - Instagram</li> <li><b>twv_</b> - Twitter</li> <li><b>tkv_</b> - TikTok</li> <li><b>ttv_</b> - Twitch</li> </ul> For example, a gid for Gangnam Style video would be <b>ytv_9bZkp7q19f0</b>", "items": {"type": "string"}}, "video_platforms": {"type": "array", "x-component": "select", "description": "An array of social platforms to use in the filter.", "x-options": {"youtube": "YouTube", "facebook": "Facebook", "instagram": "Instagram", "twitch": "Twitch", "tiktok": "TikTok"}, "items": {"type": "string"}}, "video_upload_date": {"type": "object", "x-component": "dateRange", "description": "Applies a date range limit to the date a video was uploaded. Note that this parameter has a large impact on query response times. In general, <b>the larger</b> the time span the more time the query will take to complete.\nInclude filters will default to a minimum upload date of 'last_90' if not specified. Exclude filters must specify a minimum upload date when providing the video_upload_date parameter. Due to performance reasons, this date range cannot span beyond the value allowed by your plan. To query a larger date range, you will need to issue multiple queries each with a different range and combine results.", "properties": {"min": {"type": "string", "description": "The minimum date to be included as part of a range of dates in \"YYYY-MM-DD\"", "x-component": "date"}, "max": {"type": "string", "description": "The maximum date to be included as part of a range of dates in \"YYYY-MM-DD\" format.", "x-component": "date"}}, "x-options": [{"label": "Last day", "value": "last_day"}, {"label": "Last week", "value": "last_7"}, {"label": "Last 30 days", "value": "last_30"}, {"label": "Last 90 days", "value": "last_90"}, {"label": "Last year", "value": "last_1_y"}, {"label": "Last two years", "value": "last_2_y"}, {"label": "Last three years", "value": "last_3_y"}, {"label": "All time", "value": "all_time"}, {"label": "Custom Date Range", "value": {"handler": "custom"}}]}, "video_duration": {"type": "object", "x-component": "integerRange", "description": "Applies a duration limit in seconds to use in the filter.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "video_was_live": {"type": "boolean", "description": "Specifies whether to include videos that were lived streamed. Ignored if not specified."}, "video_is_made_for_kids": {"type": "boolean", "description": "Specifies whether to include YouTube videos that were marked as \"Made for Kids\". Ignored if not specified."}, "video_is_reel": {"type": "boolean", "description": "Specifies whether to include Instagram Reel videos. Ignored if not specified."}, "video_is_360": {"type": "boolean", "description": "Specifies whether to include videos in the 360 (spherical) format. Ignored if not specified."}, "video_is_noteworthy": {"type": "boolean", "description": "Experimental feature. Specifies whether to include videos that get more views than expected given the creator's followers count and do not primarily get views from advertising. Ignored if not specified."}, "video_languages": {"type": "array", "description": "Specifies the language of the video to use in the filter. Note that available languages are currently not obtainable via a VideoFacets query. Language strings are represented as <a href=\"https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes\">ISO 639-1</a> two-letter language codes. Defaults to all languages if not specified.", "items": {"type": "string"}, "x-component": "select", "x-autocomplete": "qb/getLanguages"}, "video_list": {"type": "integer", "description": "A video custom list identifier to use in the filter. A video list represents a custom list of videos. These custom lists can be created and modified programmatically.\nSee the Custom List Methods section of the API documentation for more details. Available video lists can be obtained via the custom_list.enumerate method. Defaults to not include a video list.", "x-component": "select", "x-source": "qb/getVideoLists"}, "video_lists": {"type": "array", "description": "One or more video custom list identifiers to use in the filter. A video list represents a custom list of videos. These custom lists can be created and modified programmatically. See the Custom List Methods section of the API documentation for more details. Available video lists can be obtained via the custom_list.enumerate method. Defaults to not include a video list.", "x-component": "select", "x-source": "qb/getVideoLists", "items": {"type": "integer"}}, "video_categories": {"type": "array", "description": "Specifies a list of category names to use in the filtering. Defaults to all categories if not specified. Currently we support categories for Youtube and Facebook platforms only.", "items": {"type": "string"}, "x-component": "select", "x-autocomplete": "qb/searchVideoCategories"}, "video_entities": {"type": "array", "x-component": "select", "description": "Specifies a list of video topic identifiers to use in the filters. Defaults to all topics if not specified.", "items": {"type": "integer"}, "x-autocomplete": "qb/searchVideoTopics", "x-add": true}, "video_views": {"type": "object", "x-component": "integerRange", "description": "Applies a view limit (total number of views) to use in the filter. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "video_engagements": {"type": "object", "x-component": "integerRange", "description": "Applies a cross-platform enagement limit to use in the filter. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "hashtags": {"type": "array", "description": "Show only videos that have one or more", "x-component": "select", "x-add": true, "items": {"type": "string"}}, "mentions": {"type": "array", "description": "Show only videos that have one or more @mention in the description.", "x-component": "select", "x-add": true, "items": {"type": "string"}}, "challenges": {"type": "array", "description": "Show only videos that are part of a given challenge (TikTok only).", "x-component": "select", "x-add": true, "items": {"type": "string"}}, "audio_ids": {"type": "array", "description": "Show only videos that use one or more audio IDs (TikTok only).", "x-component": "select", "x-add": true, "items": {"type": "string"}}, "audio_titles": {"type": "array", "description": "Show only videos that use one or more audio title (TikTok only).", "x-component": "select", "x-add": true, "x-autocomplete": "qb/searchAudioTitles", "items": {"type": "string"}}, "audio_authors": {"type": "array", "description": "Show only videos that use audio of one or more audio authors (TikTok only).", "x-component": "select", "x-add": true, "x-autocomplete": "qb/searchAudioAuthors", "items": {"type": "string"}}, "audio_is_original": {"type": "boolean", "description": "Show only videos that use original audio (TikTok only)."}, "creator_types": {"type": "array", "description": "An array of creator types to use in the filter.", "x-component": "select", "x-options": {"influencer": "Influencer", "brand": "Brand", "media company": "Media Company", "aggregator": "Aggregator"}, "items": {"type": "string"}}, "creator_industries": {"type": "array", "description": "An array of creator industry identifiers to use in the filter. Defaults to all creator industries if not specified. Relevant for Brands.", "x-component": "select", "x-options": {"1": "Technology", "2": "Travel & Leisure", "3": "Music", "4": "CPG", "5": "Automotive", "6": "Financial & Insurance", "7": "Toys & Board Games", "8": "Media", "9": "Retail", "10": "Logistics & Heavy Industry", "11": "Other", "12": "Apparel & Accessories", "13": "Beverages", "14": "Personal Care & Health", "15": "Education", "16": "Public Service & Nonprofit", "17": "Food", "19": "Telecom", "20": "Pets", "21": "Sports Teams & Leagues", "22": "Gaming", "23": "Energy", "25": "Electronics", "27": "Broadcast, Cable, Radio, Film", "28": "Digital First Media", "29": "Magazine & Newspaper", "30": "Beauty"}, "items": {"type": "integer"}}, "creator_properties": {"type": "array", "x-component": "select", "description": "An array of creator property identifiers to use in the filter. Available creator properties can be obtained via a VideoFacets query. Defaults to all creator properties if not specified.", "x-autocomplete": "qb/searchProperties", "items": {"type": "integer"}}, "creator_list": {"type": "integer", "description": "A creator custom list identifier to use in the filter. A creator list represents a custom list of creators. These custom lists can be created and modified programmatically. See the Custom List section of the API documentation for more details. Available creator lists can be obtained via the custom_list.enumerate method. Defaults to not include a creator list.", "x-component": "select", "x-source": "qb/getCreatorLists"}, "creator_lists": {"type": "array", "description": "One or more creator custom list identifiers to use in the filter. A creator list represents a custom list of creators. These custom lists can be created and modified programmatically. See the Custom List section of the API documentation for more details. Available creator lists can be obtained via the custom_list.enumerate method. Defaults to not include a creator list.", "x-component": "select", "x-source": "qb/getCreatorLists", "items": {"type": "integer"}}, "creators": {"type": "array", "x-component": "select", "description": "An array of creator identifiers to use in the filter. Available creator identifiers can be obtained via the VideoFacets method or by searching for a particular creator via the CreatorSearch method. Defaults to all creators.", "x-add": true, "x-autocomplete": "qb/searchCreators", "items": {"type": "string"}}, "creator_accounts": {"type": "array", "x-component": "select", "description": "An array of creator social account identifiers to use in the filter. Available creator account identifiers can be obtained via the VideoFacets method or by the list of social accounts associated with a particular creator obtained via the CreatorDetails query. Defaults to all creator accounts if not specified.", "items": {"type": "string"}, "x-add": true}, "creator_account_followers": {"type": "object", "x-component": "integerRange", "description": "Applies a range limit to the follower count for the creator's social account that published a video (i.e., only videos whose follower counts fall within the range will be included). Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "creator_account_countries": {"type": "array", "description": "Specifies the countries associated with the creator account when limiting videos (e.g., only videos whose account are associated with the United States and France). Unlike creator_countries, this filter is applied to the country value set by the original platform. Country strings are represented as two-letter ISO 3166-1 alpha-2 codes. Defaults to all countries if not specified.", "items": {"type": "string"}, "x-component": "select", "x-autocomplete": "qb/getCountries"}, "creator_account_categories": {"type": "array", "description": "Specifies the categories associated with the creator account when limiting videos. Unlike video_categories, this filter is applied to the category value set by the original platform.", "items": {"type": "integer"}, "x-component": "select", "x-options": {"1": "Film & Animation", "2": "Autos & Vehicles", "10": "Music", "15": "Pets & Animals", "17": "Sports", "19": "Travel & Events", "20": "Gaming", "22": "People & Blogs", "23": "Comedy", "24": "Entertainment", "25": "News & Politics", "26": "Howto & Style", "27": "Education", "28": "Science & Technology", "29": "Nonprofits & Activism"}}, "creator_genres": {"type": "array", "description": "An array of content genre identifiers to use in the filter. Available content genre identifiers can be obtained via a VideoFacets query. Defaults to all content genres if not specified.", "x-component": "select", "x-options": {"2": "Travel", "3": "Music & Dance", "4": "Sports", "5": "Animals & Pets", "7": "People & Blogs", "9": "Cars, Trucks & Racing", "11": "Business", "13": "Kids Entertainment & Animation", "14": "Education", "15": "Food & Drink", "16": "Fashion & Style", "19": "Health, Fitness & Self Help", "21": "Home & DIY", "22": "News & Politics", "23": "Beauty", "24": "Film & Movies", "27": "Gaming", "32": "Family & Parenting", "33": "Science & Tech", "36": "Entertainment", "37": "General Interest"}, "items": {"type": "integer"}}, "creator_facebook_watch": {"type": "boolean", "description": "Limits the creators to those that publish a show on Facebook watch. Defaults to include all if not specified. Value can only be true or unspecified."}, "creator_countries": {"type": "array", "description": "Specifies the countries associated with the creator's accounts when limiting videos (e.g., only videos whose accounts are associated with the United States and France). Available creator countries can be obtained via a VideoFacets query. Country strings are represented as two-letter ISO 3166-1 alpha-2 codes. Defaults to all countries if not specified.", "items": {"type": "string"}, "x-component": "select", "x-autocomplete": "qb/getCountries"}, "shorts_format": {"type": "array", "description": "Limits videos to platform-specific short formats.", "items": {"type": "string"}, "x-component": "select", "x-options": {"yt_shorts": "YouTube Shorts"}}}}, "exclude_filter": {"type": "object", "description": "A video filter to be excluded by the query. Defaults to exclude no videos if not specified.", "properties": {"search": {"type": "string", "description": "The search text string to be included in the filter for searching across video titles. This string may include optional boolean search operators as described by the Help Center. Defaults to empty string if not specified.", "x-hint": "Use AND and OR operators", "x-placeholder": "I'm a placeholder"}, "search_description": {"type": "boolean", "description": "Controls whether to search the video descriptions when providing a search string parameter. Defaults to false if not specified."}, "search_keywords": {"type": "boolean", "description": "Controls whether to search the video keywords when providing a search string parameter. Defaults to false if not specified."}, "search_topics": {"type": "boolean", "description": "Controls whether to search the video topics when providing a search string parameter. Defaults to true if not specified."}, "video_gids": {"type": "array", "x-component": "select", "x-add": true, "description": "A list of specific videos to fetch. Each video is represent in the form of GID which consists of a platform prefix and original video ID. The prefixes are <ul> <li><b>ytv_</b> - YouTube</li> <li><b>fbv_</b> - Facebook</li> <li><b>igv_</b> - Instagram</li> <li><b>twv_</b> - Twitter</li> <li><b>tkv_</b> - TikTok</li> <li><b>ttv_</b> - Twitch</li> </ul> For example, a gid for Gangnam Style video would be <b>ytv_9bZkp7q19f0</b>", "items": {"type": "string"}}, "video_platforms": {"type": "array", "x-component": "select", "description": "An array of social platforms to use in the filter.", "x-options": {"youtube": "YouTube", "facebook": "Facebook", "instagram": "Instagram", "twitch": "Twitch", "tiktok": "TikTok"}, "items": {"type": "string"}}, "video_upload_date": {"type": "object", "x-component": "dateRange", "description": "Applies a date range limit to the date a video was uploaded. Note that this parameter has a large impact on query response times. In general, <b>the larger</b> the time span the more time the query will take to complete.\nInclude filters will default to a minimum upload date of 'last_90' if not specified. Exclude filters must specify a minimum upload date when providing the video_upload_date parameter. Due to performance reasons, this date range cannot span beyond the value allowed by your plan. To query a larger date range, you will need to issue multiple queries each with a different range and combine results.", "properties": {"min": {"type": "string", "description": "The minimum date to be included as part of a range of dates in \"YYYY-MM-DD\"", "x-component": "date"}, "max": {"type": "string", "description": "The maximum date to be included as part of a range of dates in \"YYYY-MM-DD\" format.", "x-component": "date"}}, "x-options": [{"label": "Last day", "value": "last_day"}, {"label": "Last week", "value": "last_7"}, {"label": "Last 30 days", "value": "last_30"}, {"label": "Last 90 days", "value": "last_90"}, {"label": "Last year", "value": "last_1_y"}, {"label": "Last two years", "value": "last_2_y"}, {"label": "Last three years", "value": "last_3_y"}, {"label": "All time", "value": "all_time"}, {"label": "Custom Date Range", "value": {"handler": "custom"}}]}, "video_duration": {"type": "object", "x-component": "integerRange", "description": "Applies a duration limit in seconds to use in the filter.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "video_was_live": {"type": "boolean", "description": "Specifies whether to include videos that were lived streamed. Ignored if not specified."}, "video_is_made_for_kids": {"type": "boolean", "description": "Specifies whether to include YouTube videos that were marked as \"Made for Kids\". Ignored if not specified."}, "video_is_reel": {"type": "boolean", "description": "Specifies whether to include Instagram Reel videos. Ignored if not specified."}, "video_is_360": {"type": "boolean", "description": "Specifies whether to include videos in the 360 (spherical) format. Ignored if not specified."}, "video_is_noteworthy": {"type": "boolean", "description": "Experimental feature. Specifies whether to include videos that get more views than expected given the creator's followers count and do not primarily get views from advertising. Ignored if not specified."}, "video_languages": {"type": "array", "description": "Specifies the language of the video to use in the filter. Note that available languages are currently not obtainable via a VideoFacets query. Language strings are represented as <a href=\"https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes\">ISO 639-1</a> two-letter language codes. Defaults to all languages if not specified.", "items": {"type": "string"}, "x-component": "select", "x-autocomplete": "qb/getLanguages"}, "video_list": {"type": "integer", "description": "A video custom list identifier to use in the filter. A video list represents a custom list of videos. These custom lists can be created and modified programmatically.\nSee the Custom List Methods section of the API documentation for more details. Available video lists can be obtained via the custom_list.enumerate method. Defaults to not include a video list.", "x-component": "select", "x-source": "qb/getVideoLists"}, "video_lists": {"type": "array", "description": "One or more video custom list identifiers to use in the filter. A video list represents a custom list of videos. These custom lists can be created and modified programmatically. See the Custom List Methods section of the API documentation for more details. Available video lists can be obtained via the custom_list.enumerate method. Defaults to not include a video list.", "x-component": "select", "x-source": "qb/getVideoLists", "items": {"type": "integer"}}, "video_categories": {"type": "array", "description": "Specifies a list of category names to use in the filtering. Defaults to all categories if not specified. Currently we support categories for Youtube and Facebook platforms only.", "items": {"type": "string"}, "x-component": "select", "x-autocomplete": "qb/searchVideoCategories"}, "video_entities": {"type": "array", "x-component": "select", "description": "Specifies a list of video topic identifiers to use in the filters. Defaults to all topics if not specified.", "items": {"type": "integer"}, "x-autocomplete": "qb/searchVideoTopics", "x-add": true}, "video_views": {"type": "object", "x-component": "integerRange", "description": "Applies a view limit (total number of views) to use in the filter. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "video_engagements": {"type": "object", "x-component": "integerRange", "description": "Applies a cross-platform enagement limit to use in the filter. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "hashtags": {"type": "array", "description": "Show only videos that have one or more", "x-component": "select", "x-add": true, "items": {"type": "string"}}, "mentions": {"type": "array", "description": "Show only videos that have one or more @mention in the description.", "x-component": "select", "x-add": true, "items": {"type": "string"}}, "challenges": {"type": "array", "description": "Show only videos that are part of a given challenge (TikTok only).", "x-component": "select", "x-add": true, "items": {"type": "string"}}, "audio_ids": {"type": "array", "description": "Show only videos that use one or more audio IDs (TikTok only).", "x-component": "select", "x-add": true, "items": {"type": "string"}}, "audio_titles": {"type": "array", "description": "Show only videos that use one or more audio title (TikTok only).", "x-component": "select", "x-add": true, "x-autocomplete": "qb/searchAudioTitles", "items": {"type": "string"}}, "audio_authors": {"type": "array", "description": "Show only videos that use audio of one or more audio authors (TikTok only).", "x-component": "select", "x-add": true, "x-autocomplete": "qb/searchAudioAuthors", "items": {"type": "string"}}, "audio_is_original": {"type": "boolean", "description": "Show only videos that use original audio (TikTok only)."}, "creator_types": {"type": "array", "description": "An array of creator types to use in the filter.", "x-component": "select", "x-options": {"influencer": "Influencer", "brand": "Brand", "media company": "Media Company", "aggregator": "Aggregator"}, "items": {"type": "string"}}, "creator_industries": {"type": "array", "description": "An array of creator industry identifiers to use in the filter. Defaults to all creator industries if not specified. Relevant for Brands.", "x-component": "select", "x-options": {"1": "Technology", "2": "Travel & Leisure", "3": "Music", "4": "CPG", "5": "Automotive", "6": "Financial & Insurance", "7": "Toys & Board Games", "8": "Media", "9": "Retail", "10": "Logistics & Heavy Industry", "11": "Other", "12": "Apparel & Accessories", "13": "Beverages", "14": "Personal Care & Health", "15": "Education", "16": "Public Service & Nonprofit", "17": "Food", "19": "Telecom", "20": "Pets", "21": "Sports Teams & Leagues", "22": "Gaming", "23": "Energy", "25": "Electronics", "27": "Broadcast, Cable, Radio, Film", "28": "Digital First Media", "29": "Magazine & Newspaper", "30": "Beauty"}, "items": {"type": "integer"}}, "creator_properties": {"type": "array", "x-component": "select", "description": "An array of creator property identifiers to use in the filter. Available creator properties can be obtained via a VideoFacets query. Defaults to all creator properties if not specified.", "x-autocomplete": "qb/searchProperties", "items": {"type": "integer"}}, "creator_list": {"type": "integer", "description": "A creator custom list identifier to use in the filter. A creator list represents a custom list of creators. These custom lists can be created and modified programmatically. See the Custom List section of the API documentation for more details. Available creator lists can be obtained via the custom_list.enumerate method. Defaults to not include a creator list.", "x-component": "select", "x-source": "qb/getCreatorLists"}, "creator_lists": {"type": "array", "description": "One or more creator custom list identifiers to use in the filter. A creator list represents a custom list of creators. These custom lists can be created and modified programmatically. See the Custom List section of the API documentation for more details. Available creator lists can be obtained via the custom_list.enumerate method. Defaults to not include a creator list.", "x-component": "select", "x-source": "qb/getCreatorLists", "items": {"type": "integer"}}, "creators": {"type": "array", "x-component": "select", "description": "An array of creator identifiers to use in the filter. Available creator identifiers can be obtained via the VideoFacets method or by searching for a particular creator via the CreatorSearch method. Defaults to all creators.", "x-add": true, "x-autocomplete": "qb/searchCreators", "items": {"type": "string"}}, "creator_accounts": {"type": "array", "x-component": "select", "description": "An array of creator social account identifiers to use in the filter. Available creator account identifiers can be obtained via the VideoFacets method or by the list of social accounts associated with a particular creator obtained via the CreatorDetails query. Defaults to all creator accounts if not specified.", "items": {"type": "string"}, "x-add": true}, "creator_account_followers": {"type": "object", "x-component": "integerRange", "description": "Applies a range limit to the follower count for the creator's social account that published a video (i.e., only videos whose follower counts fall within the range will be included). Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "creator_account_countries": {"type": "array", "description": "Specifies the countries associated with the creator account when limiting videos (e.g., only videos whose account are associated with the United States and France). Unlike creator_countries, this filter is applied to the country value set by the original platform. Country strings are represented as two-letter ISO 3166-1 alpha-2 codes. Defaults to all countries if not specified.", "items": {"type": "string"}, "x-component": "select", "x-autocomplete": "qb/getCountries"}, "creator_account_categories": {"type": "array", "description": "Specifies the categories associated with the creator account when limiting videos. Unlike video_categories, this filter is applied to the category value set by the original platform.", "items": {"type": "integer"}, "x-component": "select", "x-options": {"1": "Film & Animation", "2": "Autos & Vehicles", "10": "Music", "15": "Pets & Animals", "17": "Sports", "19": "Travel & Events", "20": "Gaming", "22": "People & Blogs", "23": "Comedy", "24": "Entertainment", "25": "News & Politics", "26": "Howto & Style", "27": "Education", "28": "Science & Technology", "29": "Nonprofits & Activism"}}, "creator_genres": {"type": "array", "description": "An array of content genre identifiers to use in the filter. Available content genre identifiers can be obtained via a VideoFacets query. Defaults to all content genres if not specified.", "x-component": "select", "x-options": {"2": "Travel", "3": "Music & Dance", "4": "Sports", "5": "Animals & Pets", "7": "People & Blogs", "9": "Cars, Trucks & Racing", "11": "Business", "13": "Kids Entertainment & Animation", "14": "Education", "15": "Food & Drink", "16": "Fashion & Style", "19": "Health, Fitness & Self Help", "21": "Home & DIY", "22": "News & Politics", "23": "Beauty", "24": "Film & Movies", "27": "Gaming", "32": "Family & Parenting", "33": "Science & Tech", "36": "Entertainment", "37": "General Interest"}, "items": {"type": "integer"}}, "creator_facebook_watch": {"type": "boolean", "description": "Limits the creators to those that publish a show on Facebook watch. Defaults to include all if not specified. Value can only be true or unspecified."}, "creator_countries": {"type": "array", "description": "Specifies the countries associated with the creator's accounts when limiting videos (e.g., only videos whose accounts are associated with the United States and France). Available creator countries can be obtained via a VideoFacets query. Country strings are represented as two-letter ISO 3166-1 alpha-2 codes. Defaults to all countries if not specified.", "items": {"type": "string"}, "x-component": "select", "x-autocomplete": "qb/getCountries"}, "shorts_format": {"type": "array", "description": "Limits videos to platform-specific short formats.", "items": {"type": "string"}, "x-component": "select", "x-options": {"yt_shorts": "YouTube Shorts"}}}}}}, "metric": {"type": "string", "description": "Name of a metric for which the trends are calculated.", "x-component": "select", "x-options": {"views": {"label": "Views", "description": "Get trends by views"}, "engagements": {"label": "Engagements", "description": "Get trends by engagments(e.g. likes, comments, shares)"}}}, "time_bucket": {"type": "string", "description": "Specify a time quantity to group trends data by. A time series of trends data will be produced using this time quantity as the time increment. If not specified, the default time_bucket of days will be used.", "x-component": "select", "x-options": {"all": {"label": "All", "description": "All data is represented in a single bucket"}, "days": {"label": "Daily", "description": "Trends data provided in daily increments"}, "weeks": {"label": "Weekly", "description": "Trends data provided in weekly increments"}, "months": {"label": "Monthly", "description": "Trends data provided in monthly increments"}, "years": {"label": "Yearly", "description": "Trends data provided in yearly increments"}, "dayofweek": {"label": "Day of Week", "description": "Trends provided by the day of a week (Mon, Tue, ...)"}}}, "segmentation_attribute": {"type": "string", "x-component": "select", "description": "An attribute to segment the results by.", "x-options": {"platform": {"label": "Platform", "description": "Group videos by video platforms"}, "category": {"label": "Video Category", "description": "Group videos by video category."}, "entity": {"label": "Video Topic", "description": "Group videos by video topics"}, "language": {"label": "Language", "description": "Group videos by video languages"}, "duration": {"label": "Duration", "description": "Group videos by video duration buckets"}, "format": {"label": "Format", "description": "Group videos by video formats (live, 360 videos)"}, "dayofweek": {"label": "Day of Week", "description": "Group videos by video upload day of a week 0 - Monday, 1 - Tuesday, ... 6 - Sunday"}, "creator": {"label": "Creator", "description": "Group videos by creators"}, "creator_type": {"label": "Creator Type", "description": "Group videos by creator types (brands, media, etc.)"}, "creator_genre": {"label": "Creator Genre", "description": "Group videos by creator genres"}, "creator_country": {"label": "Creator Country", "description": "Group videos by creator countries"}, "creator_brand_industry": {"label": "Creator Brand Industry", "description": "Group videos by a creator brand industries"}, "creator_property": {"label": "Creator Property", "description": "Group videos by creator parent properties"}, "hashtag": {"label": "Hashtags", "description": "Group videos by hashtags mentioned in the video description"}, "mention": {"label": "Mentions", "description": "Group videos by mentions added to the video description"}, "audio_title": {"label": "Audio Title", "description": "Group videos by audio title used in the video (TikTok only)"}, "audio_author": {"label": "Audio Author", "description": "Group videos by audio authors whose sound is used in the video (TikTok only)"}}}, "segmentation_depth": {"type": "integer", "description": "Defines how many attributes to return when segmentation_attribute is specified. Default value is 10. An upper limit is defined in your plan."}, "date_range": {"type": "object", "x-component": "dateRange", "description": "Defines a date range to get trends data for.", "properties": {"min": {"type": "string", "description": "The minimum date to be included as part of a range of dates in \"YYYY-MM-DD\"", "x-component": "date"}, "max": {"type": "string", "description": "The maximum date to be included as part of a range of dates in \"YYYY-MM-DD\" format.", "x-component": "date"}}, "x-options": [{"label": "Last day", "value": "last_day"}, {"label": "Last week", "value": "last_7"}, {"label": "Last 30 days", "value": "last_30"}, {"label": "Last 90 days", "value": "last_90"}, {"label": "Last year", "value": "last_1_y"}, {"label": "Last two years", "value": "last_2_y"}, {"label": "Last three years", "value": "last_3_y"}, {"label": "All time", "value": "all_time"}, {"label": "Custom Date Range", "value": {"handler": "custom"}}]}, "top": {"type": "integer", "description": "Specifies the number of top results to return per attribute value and time_bucket. The maximum value is 50, if you request more, an error will be raised. Default value 5"}, "fields": {"type": "array", "x-component": "select", "items": {"type": "string"}, "description": "A list of extra details to fetch for every video search result.", "x-options": {"video_id": {"label": "Video ID", "description": "Video identifier for a particular video."}, "title": {"label": "Title", "description": "The title of the video."}, "description": {"label": "Description", "description": "The description of the video."}, "duration": {"label": "Duration", "description": "The duration of the video in seconds."}, "views": {"label": "Views", "description": "Total number of video views. Note that this value will be null for videos from certain platforms such as Twitter, Twitch for which Tubular currently does not collect views. In addition, for Youtube Shorts views metric counts the number of times a Short starts to play or replay."}, "engagements": {"label": "Engagements", "description": "JSON object representing engagement data for this video broken down by platform."}, "tvr": {"label": "TVR", "description": "JSON object representing the Tubular Video Ratings associated with this video."}, "language": {"label": "Language", "description": "ISO 639-1 two-letter language code that specifies the language used for this video."}, "publish_date": {"label": "Publish Date", "description": "Date in YYYY-MM-DD format when a video was published"}, "publish_timestamp": {"label": "Publish Timestamp", "description": "Timestamp in YYYY-MM-DD HH:MM:SS format when a video was published"}, "publisher": {"label": "Publisher", "description": "JSON object representing information about the creator that published the video."}, "thumbnail_url": {"label": "Thumbnail", "description": "The URL of the thumbnail image for this video."}, "video_url": {"label": "Video URL", "description": "The URL of the video."}, "video_was_live": {"label": "Video was live", "description": "Specifies whether a video was lived streamed."}, "video_is_reel": {"label": "Video is Reel", "description": "Specifies whether a video is Instagram Reel."}, "video_is_360": {"label": "Video is in 360 format", "description": "Specifies whether a video is spherical."}, "video_is_made_for_kids": {"label": "Video is made for kids", "description": "Specifies whether a video is marked as kids content."}, "youtube_category": {"label": "YouTube Category", "description": "The YouTube category used when uploading the video. Empty for other platform."}, "topics": {"label": "Topics", "description": "A list of JSON objects representing legacy topics associated with this video."}, "categories": {"label": "Categories", "description": "A list of JSON objects representing categories associated with this video."}, "entities": {"label": "Video Topics (new)", "description": "A list of JSON objects representing granular video topics associated with this video."}, "keywords": {"label": "Keywords", "description": "A list of keywords of the video if available on a platform."}, "hashtags": {"label": "Hashtags", "description": "A list of hashtags extracted from a video description."}, "mentions": {"label": "Mentions", "description": "A list of mentions extracted from a description. A word prefixed with @ is considered a mention."}, "audio": {"label": "Audio Data", "description": "Provides details about audio used in the video (TikTok only)."}, "shorts_format": {"label": "Shorts Format", "description": "Specifies whether a video is a shorts format video."}}}}}}}}, "responses": {"200": {"description": "A JSON array of top videos per segment and time bucket", "headers": {"Tubular-RateLimit-Overall-Limit": {"description": "The overall rate limit is 60 requests per minute. This rate limit applies to any combination of API methods that are called within a trailing 1-minute timeframe.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Overall-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Limit": {"description": "The concurrency rate limit is set to 1. This means that no more than a single request can be made at a time (i.e., in parallel). Attempting to issue a video.search request while a video.facets request is still running, for example will cause the video.search request to return a rate_limited error.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Remaining": {"description": "Number of concurrent requests available for use.", "schema": {"type": "integer"}}, "Tubular-Quota-Rows-Consumed": {"description": "Number of rows consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Consumed": {"description": "Number of quota units consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Limit": {"description": "Total quota units available for the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Remaining": {"description": "Number of quota units remaining in the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Expires-After": {"description": "Date and time when the current quota period ends.", "schema": {"type": "string", "format": "date-time"}}, "Tubular-RateLimit-FacetSummary-Limit": {"description": "All aggregated request for either creators or videos are inherently expensive. Because of this, Tubular places a limit of no more than 6 total facet and summary requests per minute.", "schema": {"type": "integer"}}, "Tubular-RateLimit-FacetSummary-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"type": "object", "properties": {"ok": {"type": "boolean", "description": "Standard API response for success/failure."}, "summary": {"type": "array", "description": "A list of dict-like objects depicting a by-attribute breakdown of trends statistics for the given query filter.", "items": {"type": "object", "properties": {"metric": {"type": "string", "description": "A metric name trends data is retrieved for."}, "attribute_value": {"type": "string", "description": "The attribute value used for segmenting as specified in the query."}, "attribute_details": {"type": "object", "description": "The segmenting attribute details such as id and title.", "properties": {"id": {"type": "string", "description": "Id of an object used in segmentation."}, "title": {"type": "string", "description": "Title of an object used in segmentation."}}}, "value": {"type": "integer", "description": "Metric value for a given bucket."}, "time_bucket_value": {"type": "string", "description": "The time bucket value contains \"all\" if time bucket in the request is set to \"all\", otherwise it's an alias describing the time range of of the time bucket. \"YYYY-MM-DD\" - when time_bucket=days \"YYYY-MM\" - when time_bucket=months \"YYYY-WXX\" - when time_bucket=weeks where XX is the number of a year week \"YYYY\" - when time_bucket=years \"Mon/Tue/Wed...\" - when time_bucket=dayofweek"}, "start_date": {"type": "string", "format": "date", "description": "Start date of a time bucket period."}, "end_date": {"type": "string", "format": "date", "description": "End date of a time bucket period."}, "rank": {"type": "integer", "description": "Video rank in the a given attribute value and time_bucket in the range from 1 up to top where 1 is the highest position."}, "video_id": {"type": "object", "description": "Video identifier for a particular top video.", "properties": {"platform": {"type": "string", "description": "The social platform for the video."}, "id": {"type": "string", "description": "A platform-specific unique identifier tied to the video. Typically, this identifier is also included by the social platform URL where a video can be viewed (e.g., the URL \"https://www.youtube.com/watch?v=abc123\" for video id \"abc123\" is used to refer to a YouTube video with that id)."}}}, "video_details": {"type": "object", "nullable": true, "description": "Video details for a particular top video as requested by fields parameter."}}}}}}}}}, "429": {"description": "The query is quota or rate-limited.", "headers": {"Tubular-RateLimit-Overall-Limit": {"description": "The overall rate limit is 60 requests per minute. This rate limit applies to any combination of API methods that are called within a trailing 1-minute timeframe.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Overall-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Limit": {"description": "The concurrency rate limit is set to 1. This means that no more than a single request can be made at a time (i.e., in parallel). Attempting to issue a video.search request while a video.facets request is still running, for example will cause the video.search request to return a rate_limited error.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Remaining": {"description": "Number of concurrent requests available for use.", "schema": {"type": "integer"}}, "Tubular-Quota-Rows-Consumed": {"description": "Number of rows consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Consumed": {"description": "Number of quota units consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Limit": {"description": "Total quota units available for the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Remaining": {"description": "Number of quota units remaining in the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Expires-After": {"description": "Date and time when the current quota period ends.", "schema": {"type": "string", "format": "date-time"}}, "Tubular-RateLimit-FacetSummary-Limit": {"description": "All aggregated request for either creators or videos are inherently expensive. Because of this, Tubular places a limit of no more than 6 total facet and summary requests per minute.", "schema": {"type": "integer"}}, "Tubular-RateLimit-FacetSummary-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}}}}}}, "/video.insights": {"x-requires": ["api_intelligence"], "x-group": ["data", "video"], "post": {"summary": "Returns a by-attribute breakdown of summary statistics pertaining to a particular video search query.", "parameters": [{"in": "header", "description": "Tubular API key.", "name": "Api-Key", "schema": {"type": "string"}}], "requestBody": {"content": {"application/json": {"schema": {"type": "object", "required": ["query", "metrics"], "properties": {"query": {"type": "object", "description": "Defines search criteria that combines include and exclude filters.", "properties": {"savedsearch_id": {"type": "integer", "x-component": "select", "description": "Video saved search id", "x-source": "qb/getVideoSavedSearches"}, "include_filter": {"type": "object", "description": "A video filter to be included by the query. Defaults to include everything if not specified.", "properties": {"search": {"type": "string", "description": "The search text string to be included in the filter for searching across video titles. This string may include optional boolean search operators as described by the Help Center. Defaults to empty string if not specified.", "x-hint": "Use AND and OR operators", "x-placeholder": "I'm a placeholder"}, "search_description": {"type": "boolean", "description": "Controls whether to search the video descriptions when providing a search string parameter. Defaults to false if not specified."}, "search_keywords": {"type": "boolean", "description": "Controls whether to search the video keywords when providing a search string parameter. Defaults to false if not specified."}, "search_topics": {"type": "boolean", "description": "Controls whether to search the video topics when providing a search string parameter. Defaults to true if not specified."}, "video_gids": {"type": "array", "x-component": "select", "x-add": true, "description": "A list of specific videos to fetch. Each video is represent in the form of GID which consists of a platform prefix and original video ID. The prefixes are <ul> <li><b>ytv_</b> - YouTube</li> <li><b>fbv_</b> - Facebook</li> <li><b>igv_</b> - Instagram</li> <li><b>twv_</b> - Twitter</li> <li><b>tkv_</b> - TikTok</li> <li><b>ttv_</b> - Twitch</li> </ul> For example, a gid for Gangnam Style video would be <b>ytv_9bZkp7q19f0</b>", "items": {"type": "string"}}, "video_platforms": {"type": "array", "x-component": "select", "description": "An array of social platforms to use in the filter.", "x-options": {"youtube": "YouTube", "facebook": "Facebook", "instagram": "Instagram", "twitch": "Twitch", "tiktok": "TikTok"}, "items": {"type": "string"}}, "video_upload_date": {"type": "object", "x-component": "dateRange", "description": "Applies a date range limit to the date a video was uploaded. Note that this parameter has a large impact on query response times. In general, <b>the larger</b> the time span the more time the query will take to complete.\nInclude filters will default to a minimum upload date of 'last_90' if not specified. Exclude filters must specify a minimum upload date when providing the video_upload_date parameter. Due to performance reasons, this date range cannot span beyond the value allowed by your plan. To query a larger date range, you will need to issue multiple queries each with a different range and combine results.", "properties": {"min": {"type": "string", "description": "The minimum date to be included as part of a range of dates in \"YYYY-MM-DD\"", "x-component": "date"}, "max": {"type": "string", "description": "The maximum date to be included as part of a range of dates in \"YYYY-MM-DD\" format.", "x-component": "date"}}, "x-options": [{"label": "Last day", "value": "last_day"}, {"label": "Last week", "value": "last_7"}, {"label": "Last 30 days", "value": "last_30"}, {"label": "Last 90 days", "value": "last_90"}, {"label": "Last year", "value": "last_1_y"}, {"label": "Last two years", "value": "last_2_y"}, {"label": "Last three years", "value": "last_3_y"}, {"label": "All time", "value": "all_time"}, {"label": "Custom Date Range", "value": {"handler": "custom"}}]}, "video_duration": {"type": "object", "x-component": "integerRange", "description": "Applies a duration limit in seconds to use in the filter.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "video_was_live": {"type": "boolean", "description": "Specifies whether to include videos that were lived streamed. Ignored if not specified."}, "video_is_made_for_kids": {"type": "boolean", "description": "Specifies whether to include YouTube videos that were marked as \"Made for Kids\". Ignored if not specified."}, "video_is_reel": {"type": "boolean", "description": "Specifies whether to include Instagram Reel videos. Ignored if not specified."}, "video_is_360": {"type": "boolean", "description": "Specifies whether to include videos in the 360 (spherical) format. Ignored if not specified."}, "video_is_noteworthy": {"type": "boolean", "description": "Experimental feature. Specifies whether to include videos that get more views than expected given the creator's followers count and do not primarily get views from advertising. Ignored if not specified."}, "video_languages": {"type": "array", "description": "Specifies the language of the video to use in the filter. Note that available languages are currently not obtainable via a VideoFacets query. Language strings are represented as <a href=\"https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes\">ISO 639-1</a> two-letter language codes. Defaults to all languages if not specified.", "items": {"type": "string"}, "x-component": "select", "x-autocomplete": "qb/getLanguages"}, "video_list": {"type": "integer", "description": "A video custom list identifier to use in the filter. A video list represents a custom list of videos. These custom lists can be created and modified programmatically.\nSee the Custom List Methods section of the API documentation for more details. Available video lists can be obtained via the custom_list.enumerate method. Defaults to not include a video list.", "x-component": "select", "x-source": "qb/getVideoLists"}, "video_lists": {"type": "array", "description": "One or more video custom list identifiers to use in the filter. A video list represents a custom list of videos. These custom lists can be created and modified programmatically. See the Custom List Methods section of the API documentation for more details. Available video lists can be obtained via the custom_list.enumerate method. Defaults to not include a video list.", "x-component": "select", "x-source": "qb/getVideoLists", "items": {"type": "integer"}}, "video_categories": {"type": "array", "description": "Specifies a list of category names to use in the filtering. Defaults to all categories if not specified. Currently we support categories for Youtube and Facebook platforms only.", "items": {"type": "string"}, "x-component": "select", "x-autocomplete": "qb/searchVideoCategories"}, "video_entities": {"type": "array", "x-component": "select", "description": "Specifies a list of video topic identifiers to use in the filters. Defaults to all topics if not specified.", "items": {"type": "integer"}, "x-autocomplete": "qb/searchVideoTopics", "x-add": true}, "video_views": {"type": "object", "x-component": "integerRange", "description": "Applies a view limit (total number of views) to use in the filter. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "video_engagements": {"type": "object", "x-component": "integerRange", "description": "Applies a cross-platform enagement limit to use in the filter. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "hashtags": {"type": "array", "description": "Show only videos that have one or more", "x-component": "select", "x-add": true, "items": {"type": "string"}}, "mentions": {"type": "array", "description": "Show only videos that have one or more @mention in the description.", "x-component": "select", "x-add": true, "items": {"type": "string"}}, "challenges": {"type": "array", "description": "Show only videos that are part of a given challenge (TikTok only).", "x-component": "select", "x-add": true, "items": {"type": "string"}}, "audio_ids": {"type": "array", "description": "Show only videos that use one or more audio IDs (TikTok only).", "x-component": "select", "x-add": true, "items": {"type": "string"}}, "audio_titles": {"type": "array", "description": "Show only videos that use one or more audio title (TikTok only).", "x-component": "select", "x-add": true, "x-autocomplete": "qb/searchAudioTitles", "items": {"type": "string"}}, "audio_authors": {"type": "array", "description": "Show only videos that use audio of one or more audio authors (TikTok only).", "x-component": "select", "x-add": true, "x-autocomplete": "qb/searchAudioAuthors", "items": {"type": "string"}}, "audio_is_original": {"type": "boolean", "description": "Show only videos that use original audio (TikTok only)."}, "creator_types": {"type": "array", "description": "An array of creator types to use in the filter.", "x-component": "select", "x-options": {"influencer": "Influencer", "brand": "Brand", "media company": "Media Company", "aggregator": "Aggregator"}, "items": {"type": "string"}}, "creator_industries": {"type": "array", "description": "An array of creator industry identifiers to use in the filter. Defaults to all creator industries if not specified. Relevant for Brands.", "x-component": "select", "x-options": {"1": "Technology", "2": "Travel & Leisure", "3": "Music", "4": "CPG", "5": "Automotive", "6": "Financial & Insurance", "7": "Toys & Board Games", "8": "Media", "9": "Retail", "10": "Logistics & Heavy Industry", "11": "Other", "12": "Apparel & Accessories", "13": "Beverages", "14": "Personal Care & Health", "15": "Education", "16": "Public Service & Nonprofit", "17": "Food", "19": "Telecom", "20": "Pets", "21": "Sports Teams & Leagues", "22": "Gaming", "23": "Energy", "25": "Electronics", "27": "Broadcast, Cable, Radio, Film", "28": "Digital First Media", "29": "Magazine & Newspaper", "30": "Beauty"}, "items": {"type": "integer"}}, "creator_properties": {"type": "array", "x-component": "select", "description": "An array of creator property identifiers to use in the filter. Available creator properties can be obtained via a VideoFacets query. Defaults to all creator properties if not specified.", "x-autocomplete": "qb/searchProperties", "items": {"type": "integer"}}, "creator_list": {"type": "integer", "description": "A creator custom list identifier to use in the filter. A creator list represents a custom list of creators. These custom lists can be created and modified programmatically. See the Custom List section of the API documentation for more details. Available creator lists can be obtained via the custom_list.enumerate method. Defaults to not include a creator list.", "x-component": "select", "x-source": "qb/getCreatorLists"}, "creator_lists": {"type": "array", "description": "One or more creator custom list identifiers to use in the filter. A creator list represents a custom list of creators. These custom lists can be created and modified programmatically. See the Custom List section of the API documentation for more details. Available creator lists can be obtained via the custom_list.enumerate method. Defaults to not include a creator list.", "x-component": "select", "x-source": "qb/getCreatorLists", "items": {"type": "integer"}}, "creators": {"type": "array", "x-component": "select", "description": "An array of creator identifiers to use in the filter. Available creator identifiers can be obtained via the VideoFacets method or by searching for a particular creator via the CreatorSearch method. Defaults to all creators.", "x-add": true, "x-autocomplete": "qb/searchCreators", "items": {"type": "string"}}, "creator_accounts": {"type": "array", "x-component": "select", "description": "An array of creator social account identifiers to use in the filter. Available creator account identifiers can be obtained via the VideoFacets method or by the list of social accounts associated with a particular creator obtained via the CreatorDetails query. Defaults to all creator accounts if not specified.", "items": {"type": "string"}, "x-add": true}, "creator_account_followers": {"type": "object", "x-component": "integerRange", "description": "Applies a range limit to the follower count for the creator's social account that published a video (i.e., only videos whose follower counts fall within the range will be included). Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "creator_account_countries": {"type": "array", "description": "Specifies the countries associated with the creator account when limiting videos (e.g., only videos whose account are associated with the United States and France). Unlike creator_countries, this filter is applied to the country value set by the original platform. Country strings are represented as two-letter ISO 3166-1 alpha-2 codes. Defaults to all countries if not specified.", "items": {"type": "string"}, "x-component": "select", "x-autocomplete": "qb/getCountries"}, "creator_account_categories": {"type": "array", "description": "Specifies the categories associated with the creator account when limiting videos. Unlike video_categories, this filter is applied to the category value set by the original platform.", "items": {"type": "integer"}, "x-component": "select", "x-options": {"1": "Film & Animation", "2": "Autos & Vehicles", "10": "Music", "15": "Pets & Animals", "17": "Sports", "19": "Travel & Events", "20": "Gaming", "22": "People & Blogs", "23": "Comedy", "24": "Entertainment", "25": "News & Politics", "26": "Howto & Style", "27": "Education", "28": "Science & Technology", "29": "Nonprofits & Activism"}}, "creator_genres": {"type": "array", "description": "An array of content genre identifiers to use in the filter. Available content genre identifiers can be obtained via a VideoFacets query. Defaults to all content genres if not specified.", "x-component": "select", "x-options": {"2": "Travel", "3": "Music & Dance", "4": "Sports", "5": "Animals & Pets", "7": "People & Blogs", "9": "Cars, Trucks & Racing", "11": "Business", "13": "Kids Entertainment & Animation", "14": "Education", "15": "Food & Drink", "16": "Fashion & Style", "19": "Health, Fitness & Self Help", "21": "Home & DIY", "22": "News & Politics", "23": "Beauty", "24": "Film & Movies", "27": "Gaming", "32": "Family & Parenting", "33": "Science & Tech", "36": "Entertainment", "37": "General Interest"}, "items": {"type": "integer"}}, "creator_facebook_watch": {"type": "boolean", "description": "Limits the creators to those that publish a show on Facebook watch. Defaults to include all if not specified. Value can only be true or unspecified."}, "creator_countries": {"type": "array", "description": "Specifies the countries associated with the creator's accounts when limiting videos (e.g., only videos whose accounts are associated with the United States and France). Available creator countries can be obtained via a VideoFacets query. Country strings are represented as two-letter ISO 3166-1 alpha-2 codes. Defaults to all countries if not specified.", "items": {"type": "string"}, "x-component": "select", "x-autocomplete": "qb/getCountries"}, "shorts_format": {"type": "array", "description": "Limits videos to platform-specific short formats.", "items": {"type": "string"}, "x-component": "select", "x-options": {"yt_shorts": "YouTube Shorts"}}}}, "exclude_filter": {"type": "object", "description": "A video filter to be excluded by the query. Defaults to exclude no videos if not specified.", "properties": {"search": {"type": "string", "description": "The search text string to be included in the filter for searching across video titles. This string may include optional boolean search operators as described by the Help Center. Defaults to empty string if not specified.", "x-hint": "Use AND and OR operators", "x-placeholder": "I'm a placeholder"}, "search_description": {"type": "boolean", "description": "Controls whether to search the video descriptions when providing a search string parameter. Defaults to false if not specified."}, "search_keywords": {"type": "boolean", "description": "Controls whether to search the video keywords when providing a search string parameter. Defaults to false if not specified."}, "search_topics": {"type": "boolean", "description": "Controls whether to search the video topics when providing a search string parameter. Defaults to true if not specified."}, "video_gids": {"type": "array", "x-component": "select", "x-add": true, "description": "A list of specific videos to fetch. Each video is represent in the form of GID which consists of a platform prefix and original video ID. The prefixes are <ul> <li><b>ytv_</b> - YouTube</li> <li><b>fbv_</b> - Facebook</li> <li><b>igv_</b> - Instagram</li> <li><b>twv_</b> - Twitter</li> <li><b>tkv_</b> - TikTok</li> <li><b>ttv_</b> - Twitch</li> </ul> For example, a gid for Gangnam Style video would be <b>ytv_9bZkp7q19f0</b>", "items": {"type": "string"}}, "video_platforms": {"type": "array", "x-component": "select", "description": "An array of social platforms to use in the filter.", "x-options": {"youtube": "YouTube", "facebook": "Facebook", "instagram": "Instagram", "twitch": "Twitch", "tiktok": "TikTok"}, "items": {"type": "string"}}, "video_upload_date": {"type": "object", "x-component": "dateRange", "description": "Applies a date range limit to the date a video was uploaded. Note that this parameter has a large impact on query response times. In general, <b>the larger</b> the time span the more time the query will take to complete.\nInclude filters will default to a minimum upload date of 'last_90' if not specified. Exclude filters must specify a minimum upload date when providing the video_upload_date parameter. Due to performance reasons, this date range cannot span beyond the value allowed by your plan. To query a larger date range, you will need to issue multiple queries each with a different range and combine results.", "properties": {"min": {"type": "string", "description": "The minimum date to be included as part of a range of dates in \"YYYY-MM-DD\"", "x-component": "date"}, "max": {"type": "string", "description": "The maximum date to be included as part of a range of dates in \"YYYY-MM-DD\" format.", "x-component": "date"}}, "x-options": [{"label": "Last day", "value": "last_day"}, {"label": "Last week", "value": "last_7"}, {"label": "Last 30 days", "value": "last_30"}, {"label": "Last 90 days", "value": "last_90"}, {"label": "Last year", "value": "last_1_y"}, {"label": "Last two years", "value": "last_2_y"}, {"label": "Last three years", "value": "last_3_y"}, {"label": "All time", "value": "all_time"}, {"label": "Custom Date Range", "value": {"handler": "custom"}}]}, "video_duration": {"type": "object", "x-component": "integerRange", "description": "Applies a duration limit in seconds to use in the filter.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "video_was_live": {"type": "boolean", "description": "Specifies whether to include videos that were lived streamed. Ignored if not specified."}, "video_is_made_for_kids": {"type": "boolean", "description": "Specifies whether to include YouTube videos that were marked as \"Made for Kids\". Ignored if not specified."}, "video_is_reel": {"type": "boolean", "description": "Specifies whether to include Instagram Reel videos. Ignored if not specified."}, "video_is_360": {"type": "boolean", "description": "Specifies whether to include videos in the 360 (spherical) format. Ignored if not specified."}, "video_is_noteworthy": {"type": "boolean", "description": "Experimental feature. Specifies whether to include videos that get more views than expected given the creator's followers count and do not primarily get views from advertising. Ignored if not specified."}, "video_languages": {"type": "array", "description": "Specifies the language of the video to use in the filter. Note that available languages are currently not obtainable via a VideoFacets query. Language strings are represented as <a href=\"https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes\">ISO 639-1</a> two-letter language codes. Defaults to all languages if not specified.", "items": {"type": "string"}, "x-component": "select", "x-autocomplete": "qb/getLanguages"}, "video_list": {"type": "integer", "description": "A video custom list identifier to use in the filter. A video list represents a custom list of videos. These custom lists can be created and modified programmatically.\nSee the Custom List Methods section of the API documentation for more details. Available video lists can be obtained via the custom_list.enumerate method. Defaults to not include a video list.", "x-component": "select", "x-source": "qb/getVideoLists"}, "video_lists": {"type": "array", "description": "One or more video custom list identifiers to use in the filter. A video list represents a custom list of videos. These custom lists can be created and modified programmatically. See the Custom List Methods section of the API documentation for more details. Available video lists can be obtained via the custom_list.enumerate method. Defaults to not include a video list.", "x-component": "select", "x-source": "qb/getVideoLists", "items": {"type": "integer"}}, "video_categories": {"type": "array", "description": "Specifies a list of category names to use in the filtering. Defaults to all categories if not specified. Currently we support categories for Youtube and Facebook platforms only.", "items": {"type": "string"}, "x-component": "select", "x-autocomplete": "qb/searchVideoCategories"}, "video_entities": {"type": "array", "x-component": "select", "description": "Specifies a list of video topic identifiers to use in the filters. Defaults to all topics if not specified.", "items": {"type": "integer"}, "x-autocomplete": "qb/searchVideoTopics", "x-add": true}, "video_views": {"type": "object", "x-component": "integerRange", "description": "Applies a view limit (total number of views) to use in the filter. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "video_engagements": {"type": "object", "x-component": "integerRange", "description": "Applies a cross-platform enagement limit to use in the filter. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "hashtags": {"type": "array", "description": "Show only videos that have one or more", "x-component": "select", "x-add": true, "items": {"type": "string"}}, "mentions": {"type": "array", "description": "Show only videos that have one or more @mention in the description.", "x-component": "select", "x-add": true, "items": {"type": "string"}}, "challenges": {"type": "array", "description": "Show only videos that are part of a given challenge (TikTok only).", "x-component": "select", "x-add": true, "items": {"type": "string"}}, "audio_ids": {"type": "array", "description": "Show only videos that use one or more audio IDs (TikTok only).", "x-component": "select", "x-add": true, "items": {"type": "string"}}, "audio_titles": {"type": "array", "description": "Show only videos that use one or more audio title (TikTok only).", "x-component": "select", "x-add": true, "x-autocomplete": "qb/searchAudioTitles", "items": {"type": "string"}}, "audio_authors": {"type": "array", "description": "Show only videos that use audio of one or more audio authors (TikTok only).", "x-component": "select", "x-add": true, "x-autocomplete": "qb/searchAudioAuthors", "items": {"type": "string"}}, "audio_is_original": {"type": "boolean", "description": "Show only videos that use original audio (TikTok only)."}, "creator_types": {"type": "array", "description": "An array of creator types to use in the filter.", "x-component": "select", "x-options": {"influencer": "Influencer", "brand": "Brand", "media company": "Media Company", "aggregator": "Aggregator"}, "items": {"type": "string"}}, "creator_industries": {"type": "array", "description": "An array of creator industry identifiers to use in the filter. Defaults to all creator industries if not specified. Relevant for Brands.", "x-component": "select", "x-options": {"1": "Technology", "2": "Travel & Leisure", "3": "Music", "4": "CPG", "5": "Automotive", "6": "Financial & Insurance", "7": "Toys & Board Games", "8": "Media", "9": "Retail", "10": "Logistics & Heavy Industry", "11": "Other", "12": "Apparel & Accessories", "13": "Beverages", "14": "Personal Care & Health", "15": "Education", "16": "Public Service & Nonprofit", "17": "Food", "19": "Telecom", "20": "Pets", "21": "Sports Teams & Leagues", "22": "Gaming", "23": "Energy", "25": "Electronics", "27": "Broadcast, Cable, Radio, Film", "28": "Digital First Media", "29": "Magazine & Newspaper", "30": "Beauty"}, "items": {"type": "integer"}}, "creator_properties": {"type": "array", "x-component": "select", "description": "An array of creator property identifiers to use in the filter. Available creator properties can be obtained via a VideoFacets query. Defaults to all creator properties if not specified.", "x-autocomplete": "qb/searchProperties", "items": {"type": "integer"}}, "creator_list": {"type": "integer", "description": "A creator custom list identifier to use in the filter. A creator list represents a custom list of creators. These custom lists can be created and modified programmatically. See the Custom List section of the API documentation for more details. Available creator lists can be obtained via the custom_list.enumerate method. Defaults to not include a creator list.", "x-component": "select", "x-source": "qb/getCreatorLists"}, "creator_lists": {"type": "array", "description": "One or more creator custom list identifiers to use in the filter. A creator list represents a custom list of creators. These custom lists can be created and modified programmatically. See the Custom List section of the API documentation for more details. Available creator lists can be obtained via the custom_list.enumerate method. Defaults to not include a creator list.", "x-component": "select", "x-source": "qb/getCreatorLists", "items": {"type": "integer"}}, "creators": {"type": "array", "x-component": "select", "description": "An array of creator identifiers to use in the filter. Available creator identifiers can be obtained via the VideoFacets method or by searching for a particular creator via the CreatorSearch method. Defaults to all creators.", "x-add": true, "x-autocomplete": "qb/searchCreators", "items": {"type": "string"}}, "creator_accounts": {"type": "array", "x-component": "select", "description": "An array of creator social account identifiers to use in the filter. Available creator account identifiers can be obtained via the VideoFacets method or by the list of social accounts associated with a particular creator obtained via the CreatorDetails query. Defaults to all creator accounts if not specified.", "items": {"type": "string"}, "x-add": true}, "creator_account_followers": {"type": "object", "x-component": "integerRange", "description": "Applies a range limit to the follower count for the creator's social account that published a video (i.e., only videos whose follower counts fall within the range will be included). Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "creator_account_countries": {"type": "array", "description": "Specifies the countries associated with the creator account when limiting videos (e.g., only videos whose account are associated with the United States and France). Unlike creator_countries, this filter is applied to the country value set by the original platform. Country strings are represented as two-letter ISO 3166-1 alpha-2 codes. Defaults to all countries if not specified.", "items": {"type": "string"}, "x-component": "select", "x-autocomplete": "qb/getCountries"}, "creator_account_categories": {"type": "array", "description": "Specifies the categories associated with the creator account when limiting videos. Unlike video_categories, this filter is applied to the category value set by the original platform.", "items": {"type": "integer"}, "x-component": "select", "x-options": {"1": "Film & Animation", "2": "Autos & Vehicles", "10": "Music", "15": "Pets & Animals", "17": "Sports", "19": "Travel & Events", "20": "Gaming", "22": "People & Blogs", "23": "Comedy", "24": "Entertainment", "25": "News & Politics", "26": "Howto & Style", "27": "Education", "28": "Science & Technology", "29": "Nonprofits & Activism"}}, "creator_genres": {"type": "array", "description": "An array of content genre identifiers to use in the filter. Available content genre identifiers can be obtained via a VideoFacets query. Defaults to all content genres if not specified.", "x-component": "select", "x-options": {"2": "Travel", "3": "Music & Dance", "4": "Sports", "5": "Animals & Pets", "7": "People & Blogs", "9": "Cars, Trucks & Racing", "11": "Business", "13": "Kids Entertainment & Animation", "14": "Education", "15": "Food & Drink", "16": "Fashion & Style", "19": "Health, Fitness & Self Help", "21": "Home & DIY", "22": "News & Politics", "23": "Beauty", "24": "Film & Movies", "27": "Gaming", "32": "Family & Parenting", "33": "Science & Tech", "36": "Entertainment", "37": "General Interest"}, "items": {"type": "integer"}}, "creator_facebook_watch": {"type": "boolean", "description": "Limits the creators to those that publish a show on Facebook watch. Defaults to include all if not specified. Value can only be true or unspecified."}, "creator_countries": {"type": "array", "description": "Specifies the countries associated with the creator's accounts when limiting videos (e.g., only videos whose accounts are associated with the United States and France). Available creator countries can be obtained via a VideoFacets query. Country strings are represented as two-letter ISO 3166-1 alpha-2 codes. Defaults to all countries if not specified.", "items": {"type": "string"}, "x-component": "select", "x-autocomplete": "qb/getCountries"}, "shorts_format": {"type": "array", "description": "Limits videos to platform-specific short formats.", "items": {"type": "string"}, "x-component": "select", "x-options": {"yt_shorts": "YouTube Shorts"}}}}}}, "metrics": {"type": "array", "description": "Name of a metric for which the trends are calculated.", "x-component": "select", "items": {"type": "string"}, "x-options": {"accounts_count": {"label": "Accounts count", "description": "Number of distinct accounts associated with the videos for the current bucket."}, "videos_count": {"label": "Videos count", "description": "Number of videos within the current bucket."}, "views_total": {"label": "Views total", "description": "Video total views aggregated across all videos for the current bucket."}, "engagements_total": {"label": "Engagements total", "description": "Video total engagements aggregated across all videos for the current bucket."}, "v1_avg": {"label": "Average V1", "description": "Average V1 across all videos for the current bucket."}, "v2_avg": {"label": "Average V2", "description": "Average V2 across all videos for the current bucket."}, "v3_avg": {"label": "Average V3", "description": "Average V3 across all videos for the current bucket."}, "v7_avg": {"label": "Average V7", "description": "Average V7 across all videos for the current bucket."}, "v30_avg": {"label": "Average V30", "description": "Average V30 across all videos for the current bucket."}, "er1_avg": {"label": "Average ER1", "description": "Average ER1 across all videos for the current bucket."}, "er2_avg": {"label": "Average ER2", "description": "Average ER2 across all videos for the current bucket."}, "er3_avg": {"label": "Average ER3", "description": "Average ER3 across all videos for the current bucket."}, "er7_avg": {"label": "Average ER7", "description": "Average ER7 across all videos for the current bucket."}, "er30_avg": {"label": "Average ER30", "description": "Average ER30 across all videos for the current bucket."}}}, "segmentation_attribute": {"type": "string", "x-component": "select", "description": "An attribute to segment the results by.", "x-options": {"platform": {"label": "Platform", "description": "Group videos by video platforms"}, "category": {"label": "Video Category", "description": "Group videos by video category."}, "entity": {"label": "Video Topic", "description": "Group videos by video topics"}, "language": {"label": "Language", "description": "Group videos by video languages"}, "duration": {"label": "Duration", "description": "Group videos by video duration buckets"}, "format": {"label": "Format", "description": "Group videos by video formats (live, 360 videos)"}, "dayofweek": {"label": "Day of Week", "description": "Group videos by video upload day of a week 0 - Monday, 1 - Tuesday, ... 6 - Sunday"}, "creator": {"label": "Creator", "description": "Group videos by creators"}, "creator_type": {"label": "Creator Type", "description": "Group videos by creator types (brands, media, etc.)"}, "creator_genre": {"label": "Creator Genre", "description": "Group videos by creator genres"}, "creator_country": {"label": "Creator Country", "description": "Group videos by creator countries"}, "creator_brand_industry": {"label": "Creator Brand Industry", "description": "Group videos by a creator brand industries"}, "creator_property": {"label": "Creator Property", "description": "Group videos by creator parent properties"}, "hashtag": {"label": "Hashtags", "description": "Group videos by hashtags mentioned in the video description"}, "mention": {"label": "Mentions", "description": "Group videos by mentions added to the video description"}, "audio_title": {"label": "Audio Title", "description": "Group videos by audio title used in the video (TikTok only)"}, "audio_author": {"label": "Audio Author", "description": "Group videos by audio authors whose sound is used in the video (TikTok only)"}}}, "segmentation_depth": {"type": "integer", "description": "Defines how many attributes to return when segmentation_attribute is specified. Default value is 10. An upper limit is defined in your plan."}}}}}}, "responses": {"200": {"description": "A JSON array of videos", "headers": {"Tubular-RateLimit-Overall-Limit": {"description": "The overall rate limit is 60 requests per minute. This rate limit applies to any combination of API methods that are called within a trailing 1-minute timeframe.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Overall-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Limit": {"description": "The concurrency rate limit is set to 1. This means that no more than a single request can be made at a time (i.e., in parallel). Attempting to issue a video.search request while a video.facets request is still running, for example will cause the video.search request to return a rate_limited error.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Remaining": {"description": "Number of concurrent requests available for use.", "schema": {"type": "integer"}}, "Tubular-Quota-Rows-Consumed": {"description": "Number of rows consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Consumed": {"description": "Number of quota units consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Limit": {"description": "Total quota units available for the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Remaining": {"description": "Number of quota units remaining in the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Expires-After": {"description": "Date and time when the current quota period ends.", "schema": {"type": "string", "format": "date-time"}}, "Tubular-RateLimit-FacetSummary-Limit": {"description": "All aggregated request for either creators or videos are inherently expensive. Because of this, Tubular places a limit of no more than 6 total facet and summary requests per minute.", "schema": {"type": "integer"}}, "Tubular-RateLimit-FacetSummary-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"type": "object", "properties": {"ok": {"type": "boolean", "description": "Standard API response for success/failure."}, "insights": {"type": "array", "description": "A list of dict-like objects depicting a by-attribute breakdown of trends statistics for the given query filter.", "items": {"type": "object", "properties": {"metric_name": {"type": "string", "description": "A metric name insights are retrieved for."}, "metric_value": {"type": "integer", "description": "Metric value for a given bucket."}, "attribute_value": {"type": "string", "description": "The attribute value used for segmenting as specified in the query."}, "attribute_details": {"type": "object", "description": "The segmenting attribute details such as id and title.", "properties": {"id": {"type": "string", "description": "Id of an object used in segmentation."}, "title": {"type": "string", "description": "Title of an object used in segmentation."}}}}}}}}}}}, "429": {"description": "The query is quota or rate-limited.", "headers": {"Tubular-RateLimit-Overall-Limit": {"description": "The overall rate limit is 60 requests per minute. This rate limit applies to any combination of API methods that are called within a trailing 1-minute timeframe.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Overall-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Limit": {"description": "The concurrency rate limit is set to 1. This means that no more than a single request can be made at a time (i.e., in parallel). Attempting to issue a video.search request while a video.facets request is still running, for example will cause the video.search request to return a rate_limited error.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Remaining": {"description": "Number of concurrent requests available for use.", "schema": {"type": "integer"}}, "Tubular-Quota-Rows-Consumed": {"description": "Number of rows consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Consumed": {"description": "Number of quota units consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Limit": {"description": "Total quota units available for the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Remaining": {"description": "Number of quota units remaining in the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Expires-After": {"description": "Date and time when the current quota period ends.", "schema": {"type": "string", "format": "date-time"}}, "Tubular-RateLimit-FacetSummary-Limit": {"description": "All aggregated request for either creators or videos are inherently expensive. Because of this, Tubular places a limit of no more than 6 total facet and summary requests per minute.", "schema": {"type": "integer"}}, "Tubular-RateLimit-FacetSummary-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}}}}}}, "/video.facets": {"x-requires": ["api_intelligence"], "x-group": ["data", "video"], "post": {"summary": "Returns a list of up to the top 50 video filter facets (aggregations) pertaining to a particular video search query.", "parameters": [{"in": "header", "description": "Tubular API key.", "name": "Api-Key", "schema": {"type": "string"}}], "requestBody": {"content": {"application/json": {"schema": {"type": "object", "required": ["query", "facets"], "properties": {"query": {"type": "object", "description": "Defines search criteria that combines include and exclude filters.", "properties": {"savedsearch_id": {"type": "integer", "x-component": "select", "description": "Video saved search id", "x-source": "qb/getVideoSavedSearches"}, "include_filter": {"type": "object", "description": "A video filter to be included by the query. Defaults to include everything if not specified.", "properties": {"search": {"type": "string", "description": "The search text string to be included in the filter for searching across video titles. This string may include optional boolean search operators as described by the Help Center. Defaults to empty string if not specified.", "x-hint": "Use AND and OR operators", "x-placeholder": "I'm a placeholder"}, "search_description": {"type": "boolean", "description": "Controls whether to search the video descriptions when providing a search string parameter. Defaults to false if not specified."}, "search_keywords": {"type": "boolean", "description": "Controls whether to search the video keywords when providing a search string parameter. Defaults to false if not specified."}, "search_topics": {"type": "boolean", "description": "Controls whether to search the video topics when providing a search string parameter. Defaults to true if not specified."}, "video_gids": {"type": "array", "x-component": "select", "x-add": true, "description": "A list of specific videos to fetch. Each video is represent in the form of GID which consists of a platform prefix and original video ID. The prefixes are <ul> <li><b>ytv_</b> - YouTube</li> <li><b>fbv_</b> - Facebook</li> <li><b>igv_</b> - Instagram</li> <li><b>twv_</b> - Twitter</li> <li><b>tkv_</b> - TikTok</li> <li><b>ttv_</b> - Twitch</li> </ul> For example, a gid for Gangnam Style video would be <b>ytv_9bZkp7q19f0</b>", "items": {"type": "string"}}, "video_platforms": {"type": "array", "x-component": "select", "description": "An array of social platforms to use in the filter.", "x-options": {"youtube": "YouTube", "facebook": "Facebook", "instagram": "Instagram", "twitch": "Twitch", "tiktok": "TikTok"}, "items": {"type": "string"}}, "video_upload_date": {"type": "object", "x-component": "dateRange", "description": "Applies a date range limit to the date a video was uploaded. Note that this parameter has a large impact on query response times. In general, <b>the larger</b> the time span the more time the query will take to complete.\nInclude filters will default to a minimum upload date of 'last_90' if not specified. Exclude filters must specify a minimum upload date when providing the video_upload_date parameter. Due to performance reasons, this date range cannot span beyond the value allowed by your plan. To query a larger date range, you will need to issue multiple queries each with a different range and combine results.", "properties": {"min": {"type": "string", "description": "The minimum date to be included as part of a range of dates in \"YYYY-MM-DD\"", "x-component": "date"}, "max": {"type": "string", "description": "The maximum date to be included as part of a range of dates in \"YYYY-MM-DD\" format.", "x-component": "date"}}, "x-options": [{"label": "Last day", "value": "last_day"}, {"label": "Last week", "value": "last_7"}, {"label": "Last 30 days", "value": "last_30"}, {"label": "Last 90 days", "value": "last_90"}, {"label": "Last year", "value": "last_1_y"}, {"label": "Last two years", "value": "last_2_y"}, {"label": "Last three years", "value": "last_3_y"}, {"label": "All time", "value": "all_time"}, {"label": "Custom Date Range", "value": {"handler": "custom"}}]}, "video_duration": {"type": "object", "x-component": "integerRange", "description": "Applies a duration limit in seconds to use in the filter.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "video_was_live": {"type": "boolean", "description": "Specifies whether to include videos that were lived streamed. Ignored if not specified."}, "video_is_made_for_kids": {"type": "boolean", "description": "Specifies whether to include YouTube videos that were marked as \"Made for Kids\". Ignored if not specified."}, "video_is_reel": {"type": "boolean", "description": "Specifies whether to include Instagram Reel videos. Ignored if not specified."}, "video_is_360": {"type": "boolean", "description": "Specifies whether to include videos in the 360 (spherical) format. Ignored if not specified."}, "video_is_noteworthy": {"type": "boolean", "description": "Experimental feature. Specifies whether to include videos that get more views than expected given the creator's followers count and do not primarily get views from advertising. Ignored if not specified."}, "video_languages": {"type": "array", "description": "Specifies the language of the video to use in the filter. Note that available languages are currently not obtainable via a VideoFacets query. Language strings are represented as <a href=\"https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes\">ISO 639-1</a> two-letter language codes. Defaults to all languages if not specified.", "items": {"type": "string"}, "x-component": "select", "x-autocomplete": "qb/getLanguages"}, "video_list": {"type": "integer", "description": "A video custom list identifier to use in the filter. A video list represents a custom list of videos. These custom lists can be created and modified programmatically.\nSee the Custom List Methods section of the API documentation for more details. Available video lists can be obtained via the custom_list.enumerate method. Defaults to not include a video list.", "x-component": "select", "x-source": "qb/getVideoLists"}, "video_lists": {"type": "array", "description": "One or more video custom list identifiers to use in the filter. A video list represents a custom list of videos. These custom lists can be created and modified programmatically. See the Custom List Methods section of the API documentation for more details. Available video lists can be obtained via the custom_list.enumerate method. Defaults to not include a video list.", "x-component": "select", "x-source": "qb/getVideoLists", "items": {"type": "integer"}}, "video_categories": {"type": "array", "description": "Specifies a list of category names to use in the filtering. Defaults to all categories if not specified. Currently we support categories for Youtube and Facebook platforms only.", "items": {"type": "string"}, "x-component": "select", "x-autocomplete": "qb/searchVideoCategories"}, "video_entities": {"type": "array", "x-component": "select", "description": "Specifies a list of video topic identifiers to use in the filters. Defaults to all topics if not specified.", "items": {"type": "integer"}, "x-autocomplete": "qb/searchVideoTopics", "x-add": true}, "video_views": {"type": "object", "x-component": "integerRange", "description": "Applies a view limit (total number of views) to use in the filter. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "video_engagements": {"type": "object", "x-component": "integerRange", "description": "Applies a cross-platform enagement limit to use in the filter. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "hashtags": {"type": "array", "description": "Show only videos that have one or more", "x-component": "select", "x-add": true, "items": {"type": "string"}}, "mentions": {"type": "array", "description": "Show only videos that have one or more @mention in the description.", "x-component": "select", "x-add": true, "items": {"type": "string"}}, "challenges": {"type": "array", "description": "Show only videos that are part of a given challenge (TikTok only).", "x-component": "select", "x-add": true, "items": {"type": "string"}}, "audio_ids": {"type": "array", "description": "Show only videos that use one or more audio IDs (TikTok only).", "x-component": "select", "x-add": true, "items": {"type": "string"}}, "audio_titles": {"type": "array", "description": "Show only videos that use one or more audio title (TikTok only).", "x-component": "select", "x-add": true, "x-autocomplete": "qb/searchAudioTitles", "items": {"type": "string"}}, "audio_authors": {"type": "array", "description": "Show only videos that use audio of one or more audio authors (TikTok only).", "x-component": "select", "x-add": true, "x-autocomplete": "qb/searchAudioAuthors", "items": {"type": "string"}}, "audio_is_original": {"type": "boolean", "description": "Show only videos that use original audio (TikTok only)."}, "creator_types": {"type": "array", "description": "An array of creator types to use in the filter.", "x-component": "select", "x-options": {"influencer": "Influencer", "brand": "Brand", "media company": "Media Company", "aggregator": "Aggregator"}, "items": {"type": "string"}}, "creator_industries": {"type": "array", "description": "An array of creator industry identifiers to use in the filter. Defaults to all creator industries if not specified. Relevant for Brands.", "x-component": "select", "x-options": {"1": "Technology", "2": "Travel & Leisure", "3": "Music", "4": "CPG", "5": "Automotive", "6": "Financial & Insurance", "7": "Toys & Board Games", "8": "Media", "9": "Retail", "10": "Logistics & Heavy Industry", "11": "Other", "12": "Apparel & Accessories", "13": "Beverages", "14": "Personal Care & Health", "15": "Education", "16": "Public Service & Nonprofit", "17": "Food", "19": "Telecom", "20": "Pets", "21": "Sports Teams & Leagues", "22": "Gaming", "23": "Energy", "25": "Electronics", "27": "Broadcast, Cable, Radio, Film", "28": "Digital First Media", "29": "Magazine & Newspaper", "30": "Beauty"}, "items": {"type": "integer"}}, "creator_properties": {"type": "array", "x-component": "select", "description": "An array of creator property identifiers to use in the filter. Available creator properties can be obtained via a VideoFacets query. Defaults to all creator properties if not specified.", "x-autocomplete": "qb/searchProperties", "items": {"type": "integer"}}, "creator_list": {"type": "integer", "description": "A creator custom list identifier to use in the filter. A creator list represents a custom list of creators. These custom lists can be created and modified programmatically. See the Custom List section of the API documentation for more details. Available creator lists can be obtained via the custom_list.enumerate method. Defaults to not include a creator list.", "x-component": "select", "x-source": "qb/getCreatorLists"}, "creator_lists": {"type": "array", "description": "One or more creator custom list identifiers to use in the filter. A creator list represents a custom list of creators. These custom lists can be created and modified programmatically. See the Custom List section of the API documentation for more details. Available creator lists can be obtained via the custom_list.enumerate method. Defaults to not include a creator list.", "x-component": "select", "x-source": "qb/getCreatorLists", "items": {"type": "integer"}}, "creators": {"type": "array", "x-component": "select", "description": "An array of creator identifiers to use in the filter. Available creator identifiers can be obtained via the VideoFacets method or by searching for a particular creator via the CreatorSearch method. Defaults to all creators.", "x-add": true, "x-autocomplete": "qb/searchCreators", "items": {"type": "string"}}, "creator_accounts": {"type": "array", "x-component": "select", "description": "An array of creator social account identifiers to use in the filter. Available creator account identifiers can be obtained via the VideoFacets method or by the list of social accounts associated with a particular creator obtained via the CreatorDetails query. Defaults to all creator accounts if not specified.", "items": {"type": "string"}, "x-add": true}, "creator_account_followers": {"type": "object", "x-component": "integerRange", "description": "Applies a range limit to the follower count for the creator's social account that published a video (i.e., only videos whose follower counts fall within the range will be included). Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "creator_account_countries": {"type": "array", "description": "Specifies the countries associated with the creator account when limiting videos (e.g., only videos whose account are associated with the United States and France). Unlike creator_countries, this filter is applied to the country value set by the original platform. Country strings are represented as two-letter ISO 3166-1 alpha-2 codes. Defaults to all countries if not specified.", "items": {"type": "string"}, "x-component": "select", "x-autocomplete": "qb/getCountries"}, "creator_account_categories": {"type": "array", "description": "Specifies the categories associated with the creator account when limiting videos. Unlike video_categories, this filter is applied to the category value set by the original platform.", "items": {"type": "integer"}, "x-component": "select", "x-options": {"1": "Film & Animation", "2": "Autos & Vehicles", "10": "Music", "15": "Pets & Animals", "17": "Sports", "19": "Travel & Events", "20": "Gaming", "22": "People & Blogs", "23": "Comedy", "24": "Entertainment", "25": "News & Politics", "26": "Howto & Style", "27": "Education", "28": "Science & Technology", "29": "Nonprofits & Activism"}}, "creator_genres": {"type": "array", "description": "An array of content genre identifiers to use in the filter. Available content genre identifiers can be obtained via a VideoFacets query. Defaults to all content genres if not specified.", "x-component": "select", "x-options": {"2": "Travel", "3": "Music & Dance", "4": "Sports", "5": "Animals & Pets", "7": "People & Blogs", "9": "Cars, Trucks & Racing", "11": "Business", "13": "Kids Entertainment & Animation", "14": "Education", "15": "Food & Drink", "16": "Fashion & Style", "19": "Health, Fitness & Self Help", "21": "Home & DIY", "22": "News & Politics", "23": "Beauty", "24": "Film & Movies", "27": "Gaming", "32": "Family & Parenting", "33": "Science & Tech", "36": "Entertainment", "37": "General Interest"}, "items": {"type": "integer"}}, "creator_facebook_watch": {"type": "boolean", "description": "Limits the creators to those that publish a show on Facebook watch. Defaults to include all if not specified. Value can only be true or unspecified."}, "creator_countries": {"type": "array", "description": "Specifies the countries associated with the creator's accounts when limiting videos (e.g., only videos whose accounts are associated with the United States and France). Available creator countries can be obtained via a VideoFacets query. Country strings are represented as two-letter ISO 3166-1 alpha-2 codes. Defaults to all countries if not specified.", "items": {"type": "string"}, "x-component": "select", "x-autocomplete": "qb/getCountries"}, "shorts_format": {"type": "array", "description": "Limits videos to platform-specific short formats.", "items": {"type": "string"}, "x-component": "select", "x-options": {"yt_shorts": "YouTube Shorts"}}}}, "exclude_filter": {"type": "object", "description": "A video filter to be excluded by the query. Defaults to exclude no videos if not specified.", "properties": {"search": {"type": "string", "description": "The search text string to be included in the filter for searching across video titles. This string may include optional boolean search operators as described by the Help Center. Defaults to empty string if not specified.", "x-hint": "Use AND and OR operators", "x-placeholder": "I'm a placeholder"}, "search_description": {"type": "boolean", "description": "Controls whether to search the video descriptions when providing a search string parameter. Defaults to false if not specified."}, "search_keywords": {"type": "boolean", "description": "Controls whether to search the video keywords when providing a search string parameter. Defaults to false if not specified."}, "search_topics": {"type": "boolean", "description": "Controls whether to search the video topics when providing a search string parameter. Defaults to true if not specified."}, "video_gids": {"type": "array", "x-component": "select", "x-add": true, "description": "A list of specific videos to fetch. Each video is represent in the form of GID which consists of a platform prefix and original video ID. The prefixes are <ul> <li><b>ytv_</b> - YouTube</li> <li><b>fbv_</b> - Facebook</li> <li><b>igv_</b> - Instagram</li> <li><b>twv_</b> - Twitter</li> <li><b>tkv_</b> - TikTok</li> <li><b>ttv_</b> - Twitch</li> </ul> For example, a gid for Gangnam Style video would be <b>ytv_9bZkp7q19f0</b>", "items": {"type": "string"}}, "video_platforms": {"type": "array", "x-component": "select", "description": "An array of social platforms to use in the filter.", "x-options": {"youtube": "YouTube", "facebook": "Facebook", "instagram": "Instagram", "twitch": "Twitch", "tiktok": "TikTok"}, "items": {"type": "string"}}, "video_upload_date": {"type": "object", "x-component": "dateRange", "description": "Applies a date range limit to the date a video was uploaded. Note that this parameter has a large impact on query response times. In general, <b>the larger</b> the time span the more time the query will take to complete.\nInclude filters will default to a minimum upload date of 'last_90' if not specified. Exclude filters must specify a minimum upload date when providing the video_upload_date parameter. Due to performance reasons, this date range cannot span beyond the value allowed by your plan. To query a larger date range, you will need to issue multiple queries each with a different range and combine results.", "properties": {"min": {"type": "string", "description": "The minimum date to be included as part of a range of dates in \"YYYY-MM-DD\"", "x-component": "date"}, "max": {"type": "string", "description": "The maximum date to be included as part of a range of dates in \"YYYY-MM-DD\" format.", "x-component": "date"}}, "x-options": [{"label": "Last day", "value": "last_day"}, {"label": "Last week", "value": "last_7"}, {"label": "Last 30 days", "value": "last_30"}, {"label": "Last 90 days", "value": "last_90"}, {"label": "Last year", "value": "last_1_y"}, {"label": "Last two years", "value": "last_2_y"}, {"label": "Last three years", "value": "last_3_y"}, {"label": "All time", "value": "all_time"}, {"label": "Custom Date Range", "value": {"handler": "custom"}}]}, "video_duration": {"type": "object", "x-component": "integerRange", "description": "Applies a duration limit in seconds to use in the filter.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "video_was_live": {"type": "boolean", "description": "Specifies whether to include videos that were lived streamed. Ignored if not specified."}, "video_is_made_for_kids": {"type": "boolean", "description": "Specifies whether to include YouTube videos that were marked as \"Made for Kids\". Ignored if not specified."}, "video_is_reel": {"type": "boolean", "description": "Specifies whether to include Instagram Reel videos. Ignored if not specified."}, "video_is_360": {"type": "boolean", "description": "Specifies whether to include videos in the 360 (spherical) format. Ignored if not specified."}, "video_is_noteworthy": {"type": "boolean", "description": "Experimental feature. Specifies whether to include videos that get more views than expected given the creator's followers count and do not primarily get views from advertising. Ignored if not specified."}, "video_languages": {"type": "array", "description": "Specifies the language of the video to use in the filter. Note that available languages are currently not obtainable via a VideoFacets query. Language strings are represented as <a href=\"https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes\">ISO 639-1</a> two-letter language codes. Defaults to all languages if not specified.", "items": {"type": "string"}, "x-component": "select", "x-autocomplete": "qb/getLanguages"}, "video_list": {"type": "integer", "description": "A video custom list identifier to use in the filter. A video list represents a custom list of videos. These custom lists can be created and modified programmatically.\nSee the Custom List Methods section of the API documentation for more details. Available video lists can be obtained via the custom_list.enumerate method. Defaults to not include a video list.", "x-component": "select", "x-source": "qb/getVideoLists"}, "video_lists": {"type": "array", "description": "One or more video custom list identifiers to use in the filter. A video list represents a custom list of videos. These custom lists can be created and modified programmatically. See the Custom List Methods section of the API documentation for more details. Available video lists can be obtained via the custom_list.enumerate method. Defaults to not include a video list.", "x-component": "select", "x-source": "qb/getVideoLists", "items": {"type": "integer"}}, "video_categories": {"type": "array", "description": "Specifies a list of category names to use in the filtering. Defaults to all categories if not specified. Currently we support categories for Youtube and Facebook platforms only.", "items": {"type": "string"}, "x-component": "select", "x-autocomplete": "qb/searchVideoCategories"}, "video_entities": {"type": "array", "x-component": "select", "description": "Specifies a list of video topic identifiers to use in the filters. Defaults to all topics if not specified.", "items": {"type": "integer"}, "x-autocomplete": "qb/searchVideoTopics", "x-add": true}, "video_views": {"type": "object", "x-component": "integerRange", "description": "Applies a view limit (total number of views) to use in the filter. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "video_engagements": {"type": "object", "x-component": "integerRange", "description": "Applies a cross-platform enagement limit to use in the filter. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "hashtags": {"type": "array", "description": "Show only videos that have one or more", "x-component": "select", "x-add": true, "items": {"type": "string"}}, "mentions": {"type": "array", "description": "Show only videos that have one or more @mention in the description.", "x-component": "select", "x-add": true, "items": {"type": "string"}}, "challenges": {"type": "array", "description": "Show only videos that are part of a given challenge (TikTok only).", "x-component": "select", "x-add": true, "items": {"type": "string"}}, "audio_ids": {"type": "array", "description": "Show only videos that use one or more audio IDs (TikTok only).", "x-component": "select", "x-add": true, "items": {"type": "string"}}, "audio_titles": {"type": "array", "description": "Show only videos that use one or more audio title (TikTok only).", "x-component": "select", "x-add": true, "x-autocomplete": "qb/searchAudioTitles", "items": {"type": "string"}}, "audio_authors": {"type": "array", "description": "Show only videos that use audio of one or more audio authors (TikTok only).", "x-component": "select", "x-add": true, "x-autocomplete": "qb/searchAudioAuthors", "items": {"type": "string"}}, "audio_is_original": {"type": "boolean", "description": "Show only videos that use original audio (TikTok only)."}, "creator_types": {"type": "array", "description": "An array of creator types to use in the filter.", "x-component": "select", "x-options": {"influencer": "Influencer", "brand": "Brand", "media company": "Media Company", "aggregator": "Aggregator"}, "items": {"type": "string"}}, "creator_industries": {"type": "array", "description": "An array of creator industry identifiers to use in the filter. Defaults to all creator industries if not specified. Relevant for Brands.", "x-component": "select", "x-options": {"1": "Technology", "2": "Travel & Leisure", "3": "Music", "4": "CPG", "5": "Automotive", "6": "Financial & Insurance", "7": "Toys & Board Games", "8": "Media", "9": "Retail", "10": "Logistics & Heavy Industry", "11": "Other", "12": "Apparel & Accessories", "13": "Beverages", "14": "Personal Care & Health", "15": "Education", "16": "Public Service & Nonprofit", "17": "Food", "19": "Telecom", "20": "Pets", "21": "Sports Teams & Leagues", "22": "Gaming", "23": "Energy", "25": "Electronics", "27": "Broadcast, Cable, Radio, Film", "28": "Digital First Media", "29": "Magazine & Newspaper", "30": "Beauty"}, "items": {"type": "integer"}}, "creator_properties": {"type": "array", "x-component": "select", "description": "An array of creator property identifiers to use in the filter. Available creator properties can be obtained via a VideoFacets query. Defaults to all creator properties if not specified.", "x-autocomplete": "qb/searchProperties", "items": {"type": "integer"}}, "creator_list": {"type": "integer", "description": "A creator custom list identifier to use in the filter. A creator list represents a custom list of creators. These custom lists can be created and modified programmatically. See the Custom List section of the API documentation for more details. Available creator lists can be obtained via the custom_list.enumerate method. Defaults to not include a creator list.", "x-component": "select", "x-source": "qb/getCreatorLists"}, "creator_lists": {"type": "array", "description": "One or more creator custom list identifiers to use in the filter. A creator list represents a custom list of creators. These custom lists can be created and modified programmatically. See the Custom List section of the API documentation for more details. Available creator lists can be obtained via the custom_list.enumerate method. Defaults to not include a creator list.", "x-component": "select", "x-source": "qb/getCreatorLists", "items": {"type": "integer"}}, "creators": {"type": "array", "x-component": "select", "description": "An array of creator identifiers to use in the filter. Available creator identifiers can be obtained via the VideoFacets method or by searching for a particular creator via the CreatorSearch method. Defaults to all creators.", "x-add": true, "x-autocomplete": "qb/searchCreators", "items": {"type": "string"}}, "creator_accounts": {"type": "array", "x-component": "select", "description": "An array of creator social account identifiers to use in the filter. Available creator account identifiers can be obtained via the VideoFacets method or by the list of social accounts associated with a particular creator obtained via the CreatorDetails query. Defaults to all creator accounts if not specified.", "items": {"type": "string"}, "x-add": true}, "creator_account_followers": {"type": "object", "x-component": "integerRange", "description": "Applies a range limit to the follower count for the creator's social account that published a video (i.e., only videos whose follower counts fall within the range will be included). Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "creator_account_countries": {"type": "array", "description": "Specifies the countries associated with the creator account when limiting videos (e.g., only videos whose account are associated with the United States and France). Unlike creator_countries, this filter is applied to the country value set by the original platform. Country strings are represented as two-letter ISO 3166-1 alpha-2 codes. Defaults to all countries if not specified.", "items": {"type": "string"}, "x-component": "select", "x-autocomplete": "qb/getCountries"}, "creator_account_categories": {"type": "array", "description": "Specifies the categories associated with the creator account when limiting videos. Unlike video_categories, this filter is applied to the category value set by the original platform.", "items": {"type": "integer"}, "x-component": "select", "x-options": {"1": "Film & Animation", "2": "Autos & Vehicles", "10": "Music", "15": "Pets & Animals", "17": "Sports", "19": "Travel & Events", "20": "Gaming", "22": "People & Blogs", "23": "Comedy", "24": "Entertainment", "25": "News & Politics", "26": "Howto & Style", "27": "Education", "28": "Science & Technology", "29": "Nonprofits & Activism"}}, "creator_genres": {"type": "array", "description": "An array of content genre identifiers to use in the filter. Available content genre identifiers can be obtained via a VideoFacets query. Defaults to all content genres if not specified.", "x-component": "select", "x-options": {"2": "Travel", "3": "Music & Dance", "4": "Sports", "5": "Animals & Pets", "7": "People & Blogs", "9": "Cars, Trucks & Racing", "11": "Business", "13": "Kids Entertainment & Animation", "14": "Education", "15": "Food & Drink", "16": "Fashion & Style", "19": "Health, Fitness & Self Help", "21": "Home & DIY", "22": "News & Politics", "23": "Beauty", "24": "Film & Movies", "27": "Gaming", "32": "Family & Parenting", "33": "Science & Tech", "36": "Entertainment", "37": "General Interest"}, "items": {"type": "integer"}}, "creator_facebook_watch": {"type": "boolean", "description": "Limits the creators to those that publish a show on Facebook watch. Defaults to include all if not specified. Value can only be true or unspecified."}, "creator_countries": {"type": "array", "description": "Specifies the countries associated with the creator's accounts when limiting videos (e.g., only videos whose accounts are associated with the United States and France). Available creator countries can be obtained via a VideoFacets query. Country strings are represented as two-letter ISO 3166-1 alpha-2 codes. Defaults to all countries if not specified.", "items": {"type": "string"}, "x-component": "select", "x-autocomplete": "qb/getCountries"}, "shorts_format": {"type": "array", "description": "Limits videos to platform-specific short formats.", "items": {"type": "string"}, "x-component": "select", "x-options": {"yt_shorts": "YouTube Shorts"}}}}}}, "facets": {"type": "array", "description": "A list of metrics.", "x-component": "select", "items": {"type": "string"}, "x-options": {"video_platforms": "Video platforms", "video_topics": "Video topics", "video_categories": "Video categories", "creators": "Creators", "creator_types": "Creator Types", "creator_industries": "Creator Industries", "creator_properties": "Creator Properties", "creator_genres": "Creator Genres", "creator_countries": "Creator Countries"}}}}}}}, "responses": {"200": {"description": "Number of videos per category/attribute and sorted by the most frequent ones.", "headers": {"Tubular-RateLimit-Overall-Limit": {"description": "The overall rate limit is 60 requests per minute. This rate limit applies to any combination of API methods that are called within a trailing 1-minute timeframe.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Overall-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Limit": {"description": "The concurrency rate limit is set to 1. This means that no more than a single request can be made at a time (i.e., in parallel). Attempting to issue a video.search request while a video.facets request is still running, for example will cause the video.search request to return a rate_limited error.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Remaining": {"description": "Number of concurrent requests available for use.", "schema": {"type": "integer"}}, "Tubular-Quota-Rows-Consumed": {"description": "Number of rows consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Consumed": {"description": "Number of quota units consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Limit": {"description": "Total quota units available for the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Remaining": {"description": "Number of quota units remaining in the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Expires-After": {"description": "Date and time when the current quota period ends.", "schema": {"type": "string", "format": "date-time"}}, "Tubular-RateLimit-FacetSummary-Limit": {"description": "All aggregated request for either creators or videos are inherently expensive. Because of this, Tubular places a limit of no more than 6 total facet and summary requests per minute.", "schema": {"type": "integer"}}, "Tubular-RateLimit-FacetSummary-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"type": "object", "properties": {"ok": {"type": "boolean", "description": "Number of videos per category/attribute and sorted by the most frequent ones."}, "facets": {"type": "array", "description": "A list of facets associated with the requested filters.", "items": {"type": "object", "properties": {"filter": {"type": "string", "description": "The filter name pertaining to the list of facet metrics provided by this object."}, "metrics": {"type": "array", "description": "A list of video facet metrics for a particular filter.", "items": {"type": "object", "properties": {"id": {"type": "integer", "description": "Facet identifier for the current facet. A facet id is guaranteed to be globally unique for a particular filter type (e.g., no two facets will ever use the same id across all creator_properties)."}, "count": {"type": "integer", "description": "The distinct count of unique occurrences for a particular facet value and filter query combination."}, "title": {"type": "string", "description": "The title of a particular facet value. This is intended to be for display purposes only. A null value means that the facet id should also be used for display purposes (e.g., for \"video_platforms\" and \"creator_types\")."}}}}}}}}}}}}, "429": {"description": "The query is quota or rate-limited.", "headers": {"Tubular-RateLimit-Overall-Limit": {"description": "The overall rate limit is 60 requests per minute. This rate limit applies to any combination of API methods that are called within a trailing 1-minute timeframe.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Overall-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Limit": {"description": "The concurrency rate limit is set to 1. This means that no more than a single request can be made at a time (i.e., in parallel). Attempting to issue a video.search request while a video.facets request is still running, for example will cause the video.search request to return a rate_limited error.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Remaining": {"description": "Number of concurrent requests available for use.", "schema": {"type": "integer"}}, "Tubular-Quota-Rows-Consumed": {"description": "Number of rows consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Consumed": {"description": "Number of quota units consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Limit": {"description": "Total quota units available for the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Remaining": {"description": "Number of quota units remaining in the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Expires-After": {"description": "Date and time when the current quota period ends.", "schema": {"type": "string", "format": "date-time"}}, "Tubular-RateLimit-FacetSummary-Limit": {"description": "All aggregated request for either creators or videos are inherently expensive. Because of this, Tubular places a limit of no more than 6 total facet and summary requests per minute.", "schema": {"type": "integer"}}, "Tubular-RateLimit-FacetSummary-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}}}}}}, "/video.trends": {"x-requires": ["api_intelligence"], "x-group": ["data", "video"], "post": {"summary": "Get historical daily metrics for a a particular video.", "parameters": [{"in": "header", "description": "Tubular API key.", "name": "Api-Key", "schema": {"type": "string"}}], "requestBody": {"content": {"application/json": {"schema": {"type": "object", "required": ["video_id", "metrics", "date_range"], "properties": {"video_id": {"type": "object", "description": "A video identifier representing the video that trends should be retrieved for.", "properties": {"platform": {"type": "string", "description": "The social platform for the video.", "x-component": "select", "x-options": {"youtube": "YouTube", "facebook": "Facebook", "instagram": "Instagram", "twitch": "Twitch", "tiktok": "TikTok"}}, "id": {"type": "string", "description": "A platform-specific unique identifier tied to the video. Typically, this identifier is also included by the social platform URL where a video can be viewed (e.g., the URL \"https://www.youtube.com/watch?v=abc123\" for video id \"abc123\" is used to refer to a YouTube video with that id)."}}}, "metrics": {"type": "array", "description": "A list of metrics to retrieve trends for. Note that the \"views\" metric is currently unavailable for the Twitter and Twitch platforms.", "x-component": "select", "items": {"type": "string"}, "x-options": {"views": "Views", "engagements": "Engagements"}}, "date_range": {"type": "object", "x-component": "dateRange", "description": "Defines a date range to get trends data for.", "properties": {"min": {"type": "string", "description": "The minimum date to be included as part of a range of dates in \"YYYY-MM-DD\"", "x-component": "date"}, "max": {"type": "string", "description": "The maximum date to be included as part of a range of dates in \"YYYY-MM-DD\" format.", "x-component": "date"}}, "x-options": [{"label": "Last day", "value": "last_day"}, {"label": "Last week", "value": "last_7"}, {"label": "Last 30 days", "value": "last_30"}, {"label": "Last 90 days", "value": "last_90"}, {"label": "Last year", "value": "last_1_y"}, {"label": "Last two years", "value": "last_2_y"}, {"label": "Last three years", "value": "last_3_y"}, {"label": "All time", "value": "all_time"}, {"label": "Custom Date Range", "value": {"handler": "custom"}}]}}}}}}, "responses": {"200": {"description": "Status of operation", "headers": {"Tubular-RateLimit-Overall-Limit": {"description": "The overall rate limit is 60 requests per minute. This rate limit applies to any combination of API methods that are called within a trailing 1-minute timeframe.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Overall-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Limit": {"description": "The concurrency rate limit is set to 1. This means that no more than a single request can be made at a time (i.e., in parallel). Attempting to issue a video.search request while a video.facets request is still running, for example will cause the video.search request to return a rate_limited error.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Remaining": {"description": "Number of concurrent requests available for use.", "schema": {"type": "integer"}}, "Tubular-Quota-Rows-Consumed": {"description": "Number of rows consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Consumed": {"description": "Number of quota units consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Limit": {"description": "Total quota units available for the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Remaining": {"description": "Number of quota units remaining in the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Expires-After": {"description": "Date and time when the current quota period ends.", "schema": {"type": "string", "format": "date-time"}}}, "content": {"application/json": {"schema": {"type": "object", "properties": {"ok": {"type": "boolean", "description": "Standard API response for success/failure."}, "trends": {"type": "array", "description": "A list of metrics over time for each requested metric.", "items": {"type": "object", "properties": {"metric": {"type": "string", "description": "The metric associated with the current trends."}, "dates": {"type": "array", "description": "A list of date strings corresponding to metric values over time.", "items": {"type": "string"}}, "values": {"type": "array", "description": "A list of values accumulated over a particular day for the corresponding metric. For example, a value of 400 for the views metric for a particular date means that the video acquired 400 views on that day.", "items": {"type": "integer"}}, "totals": {"type": "array", "description": "A running total of values for the corresponding metric. For example, a value of 980 for the engagements metric for a particular date means that there have been a cumulative total of 980 engagements up to the day.", "items": {"type": "integer"}}}}}}}}}}, "429": {"description": "The query is rate-limited.", "headers": {"Tubular-RateLimit-Overall-Limit": {"description": "The overall rate limit is 60 requests per minute. This rate limit applies to any combination of API methods that are called within a trailing 1-minute timeframe.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Overall-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Limit": {"description": "The concurrency rate limit is set to 1. This means that no more than a single request can be made at a time (i.e., in parallel). Attempting to issue a video.search request while a video.facets request is still running, for example will cause the video.search request to return a rate_limited error.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Remaining": {"description": "Number of concurrent requests available for use.", "schema": {"type": "integer"}}, "Tubular-Quota-Rows-Consumed": {"description": "Number of rows consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Consumed": {"description": "Number of quota units consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Limit": {"description": "Total quota units available for the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Remaining": {"description": "Number of quota units remaining in the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Expires-After": {"description": "Date and time when the current quota period ends.", "schema": {"type": "string", "format": "date-time"}}}}}}}, "/video.details": {"x-requires": ["api_intelligence"], "x-group": ["data", "video"], "post": {"summary": "Get video details for one ore more video IDs.", "parameters": [{"in": "header", "description": "Tubular API key.", "name": "Api-Key", "schema": {"type": "string"}}], "requestBody": {"content": {"application/json": {"schema": {"type": "object", "required": ["video_ids"], "properties": {"video_ids": {"type": "array", "description": "A list of one or more video identifiers representing the videos that should be retrieved. Video IDs can be obtained via a video.search query. For performance reasons, the number of video IDs queried cannot exceed 200.", "items": {"type": "object", "required": ["platform", "id"], "properties": {"platform": {"type": "string", "description": "The social platform for the video.", "x-component": "select", "x-options": {"youtube": "YouTube", "facebook": "Facebook", "instagram": "Instagram", "twitch": "Twitch"}}, "id": {"type": "string", "description": "A platform-specific unique identifier tied to the video. Typically, this identifier is also included by the social platform URL where a video can be viewed (e.g., the URL \"https://www.youtube.com/watch?v=abc123\" for video id \"abc123\" is used to refer to a YouTube video with that id)."}}}}}}}}}, "responses": {"200": {"description": "Status of operation", "headers": {"Tubular-RateLimit-Overall-Limit": {"description": "The overall rate limit is 60 requests per minute. This rate limit applies to any combination of API methods that are called within a trailing 1-minute timeframe.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Overall-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Limit": {"description": "The concurrency rate limit is set to 1. This means that no more than a single request can be made at a time (i.e., in parallel). Attempting to issue a video.search request while a video.facets request is still running, for example will cause the video.search request to return a rate_limited error.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Remaining": {"description": "Number of concurrent requests available for use.", "schema": {"type": "integer"}}, "Tubular-Quota-Rows-Consumed": {"description": "Number of rows consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Consumed": {"description": "Number of quota units consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Limit": {"description": "Total quota units available for the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Remaining": {"description": "Number of quota units remaining in the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Expires-After": {"description": "Date and time when the current quota period ends.", "schema": {"type": "string", "format": "date-time"}}, "Tubular-RateLimit-UniqueVideoLimit-Limit": {"description": "Defines the total number of unique videos a client can retrieve in the current month.", "schema": {"type": "integer"}}, "Tubular-RateLimit-UniqueVideoLimit-Remaining": {"description": "A number of unique creators left in this month.", "schema": {"type": "integer"}}, "Tubular-RateLimit-UniqueVideoLimit-ExpiresAfter": {"description": "Specifies the date when the quota resets. Usually a beginning of each month.", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"type": "object", "properties": {"ok": {"type": "boolean", "description": "Standard API response for success/failure."}, "videos": {"type": "array", "description": "A list of JSON objects representing video information for the requested video IDs.", "items": {"type": "object", "properties": {"video_id": {"type": "object", "description": "Video ID object representing unique video identifier across all platforms.", "properties": {"platform": {"type": "string", "description": "The social platform for the video."}, "id": {"type": "string", "description": "Video identifier for a particular video. A video id is guaranteed to be globally unique (i.e., no two videos will ever use the same id). You can use a video.details query to gather more information about a specific video."}}}, "title": {"type": "string", "description": "The title of the video."}, "description": {"type": "string", "description": "The description of the video."}, "keywords": {"type": "array", "description": "The keywords of the video if available on a platform.", "items": {"type": "string"}}, "hashtags": {"type": "array", "description": "A list of hashtags added to the video description in the form of", "items": {"type": "string"}}, "mentions": {"type": "array", "description": "A list of mentions in the video taken from the description in the form of @someone.", "items": {"type": "string"}}, "audio": {"type": "object", "description": "Audio used in the video (TikTok only).", "properties": {"id": {"type": "string", "description": "Unique song identifier"}, "title": {"type": "string", "description": "Song/audio title"}, "author": {"type": "string", "description": "Song/audio author name"}, "is_original": {"type": "boolean", "description": "Whether a sound is original"}}}, "platform": {"type": "string", "description": "The social platform where the video was published."}, "publish_date": {"type": "string", "x-component": "date", "description": "Date in YYYY-MM-DD format when a video was published"}, "publish_timestamp": {"type": "string", "x-component": "date-time", "description": "Timestamp in YYYY-MM-DD HH:MM:SS format when a video was published"}, "publisher": {"type": "object", "description": "JSON object representing information about the creator that published the video.", "properties": {"creator_id": {"type": "string", "description": "Publisher creator ID"}, "creator_name": {"type": "string", "description": "Publisher name"}, "creator_type": {"type": "string", "description": "Publisher type"}, "creator_country": {"type": "string", "description": "Creator country"}, "creator_genre": {"type": "integer", "description": "Creator genre"}}}, "thumbnail_url": {"type": "string", "description": "The URL of the thumbnail image for this video."}, "video_url": {"type": "string", "description": "The URL of the original video on the platform."}, "duration": {"type": "integer", "description": "Video duration in seconds"}, "youtube_category": {"type": "string", "description": "The YouTube category used when uploading the video. Note that this field is specific to YouTube videos and will otherwise be empty."}, "video_was_live": {"type": "boolean", "description": "Specifies whether a video was lived streamed."}, "video_is_reel": {"type": "boolean", "description": "Specifies whether a video is Instagram Reel."}, "video_is_360": {"type": "boolean", "description": "Specifies whether a video is in 360 (spherical) format."}, "video_is_made_for_kids": {"type": "boolean", "description": "Specifies whether a video is marked as kids content."}, "views": {"type": "integer", "description": "Total number of video views. Note that this value will be null for videos from certain platforms such as Twitter and Twitch, for which Tubular currently does not collect views."}, "engagements": {"type": "object", "description": "Total number of video engagements.", "properties": {"total": {"type": "integer", "description": "Total number of video engagements."}, "breakdown": {"type": "array", "description": "Breakdown of engagements by their type", "items": {"type": "object", "properties": {"platform": {"type": "string"}, "total": {"type": "integer"}, "likes": {"type": "integer"}, "shares": {"type": "integer"}, "comments": {"type": "integer"}, "tweets": {"type": "integer"}, "favorites": {"type": "integer"}, "hahas": {"type": "integer"}, "wows": {"type": "integer"}, "loves": {"type": "integer"}, "sads": {"type": "integer"}, "angrys": {"type": "integer"}}}}}}, "language": {"type": "string", "description": "ISO 639-1 two-letter language code that specifies the language used for this video."}, "topics": {"type": "object", "description": "A list of JSON objects representing different topics associated with this video.", "properties": {"topic_id": {"type": "string", "description": "Unique topic identifier"}, "topic_name": {"type": "string", "description": "Topic name"}}}, "categories": {"type": "object", "description": "A list of JSON objects representing different categories associated with this video.", "properties": {"category_name": {"type": "string", "description": "Name of the category associated with the video."}}}, "tvr": {"type": "object", "description": "JSON object representing the Tubular Video Ratings associated with this video. Note that this object will be null for videos from certain platforms such as Twitter and Twitch, for which Tubular currently does not collect views.", "properties": {"v1": {"type": "integer", "description": "The total views of a video during its first day"}, "v2": {"type": "integer", "description": "The total views of a video during its first 2 days"}, "v3": {"type": "integer", "description": "The total views of a video during its first 3 days"}, "v7": {"type": "integer", "description": "The total views of a video during its first 7 days"}, "v30": {"type": "integer", "description": "The total views of a video during its first 30 days"}, "e1": {"type": "integer", "description": "The total engagements of a video during its first day"}, "e2": {"type": "integer", "description": "The total engagements of a video during its first 2 days"}, "e3": {"type": "integer", "description": "The total engagements of a video during its first 3 days"}, "e7": {"type": "integer", "description": "The total engagements of a video during its first 7 days"}, "e30": {"type": "integer", "description": "The total engagements of a video during its first 30 days"}, "er1": {"type": "number", "format": "double", "x-component": "double", "description": "The first day [engagements / views] on a video compared to a platform average baseline"}, "er2": {"type": "number", "format": "double", "x-component": "double", "description": "The first 2 day [engagements / views] on a video compared to a platform average baseline"}, "er3": {"type": "number", "format": "double", "x-component": "double", "description": "The first 3 day [engagements / views] on a video compared to a platform average baseline"}, "er7": {"type": "number", "format": "double", "x-component": "double", "description": "The first 7 day [engagements / views] on a video compared to a platform average baseline"}, "er30": {"type": "number", "format": "double", "x-component": "double", "description": "The first 30 day [engagements / views] on a video compared to a platform average baseline"}}}}}}}}}}}, "429": {"description": "The query is rate-limited.", "headers": {"Tubular-RateLimit-Overall-Limit": {"description": "The overall rate limit is 60 requests per minute. This rate limit applies to any combination of API methods that are called within a trailing 1-minute timeframe.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Overall-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Limit": {"description": "The concurrency rate limit is set to 1. This means that no more than a single request can be made at a time (i.e., in parallel). Attempting to issue a video.search request while a video.facets request is still running, for example will cause the video.search request to return a rate_limited error.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Remaining": {"description": "Number of concurrent requests available for use.", "schema": {"type": "integer"}}, "Tubular-Quota-Rows-Consumed": {"description": "Number of rows consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Consumed": {"description": "Number of quota units consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Limit": {"description": "Total quota units available for the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Remaining": {"description": "Number of quota units remaining in the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Expires-After": {"description": "Date and time when the current quota period ends.", "schema": {"type": "string", "format": "date-time"}}, "Tubular-RateLimit-UniqueVideoLimit-Limit": {"description": "Defines the total number of unique videos a client can retrieve in the current month.", "schema": {"type": "integer"}}, "Tubular-RateLimit-UniqueVideoLimit-Remaining": {"description": "A number of unique creators left in this month.", "schema": {"type": "integer"}}, "Tubular-RateLimit-UniqueVideoLimit-ExpiresAfter": {"description": "Specifies the date when the quota resets. Usually a beginning of each month.", "schema": {"type": "integer"}}}}}}}, "/video.audience_overlap": {"x-requires": ["api_intelligence"], "x-group": ["data", "video", "audience"], "post": {"summary": "Find videos or creators that are also watched by the audience of the source videos.", "parameters": [{"in": "header", "description": "Tubular API key.", "name": "Api-Key", "schema": {"type": "string"}}], "requestBody": {"content": {"application/json": {"schema": {"type": "object", "required": ["video_ids", "type", "platform"], "properties": {"video_ids": {"type": "array", "description": "A list of video identifiers representing the videos that the audience overlap should be calculated against.", "items": {"type": "object", "required": ["platform", "id"], "properties": {"platform": {"type": "string", "description": "The social platform for the video.", "x-component": "select", "x-options": {"youtube": "YouTube", "facebook": "Facebook", "instagram": "Instagram", "twitch": "Twitch"}}, "id": {"type": "string", "description": "A platform-specific unique identifier tied to the video. Typically, this identifier is also included by the social platform URL where a video can be viewed (e.g., the URL \"https://www.youtube.com/watch?v=abc123\" for video id \"abc123\" is used to refer to a YouTube video with that id)."}}}}, "type": {"type": "string", "x-component": "select", "description": "Specifies whether to calculate a list of either videos or creators the audience of the specified video_ids also watches.", "x-options": {"video": "Video", "creator": "Creator"}}, "platform": {"type": "string", "x-component": "select", "description": "Tubular requires specification of platform for this analysis because each platform has its own \"universe\" of audience members. These universes are not equal, either in terms of size or user behavior, so even if we tried to link audience members across platforms (which we do not), any type of cross-platform analysis would bias towards one platform or another.", "x-options": {"youtube": "YouTube", "facebook": "Facebook", "instagram": "Instagram"}}, "result_ids": {"type": "array", "x-component": "select", "x-add": true, "x-hint": "To add an item, type creator or video ID and press enter", "description": "A list of creator or video IDs allowed in the results.", "items": {"type": "string"}}, "sort": {"type": "object", "description": "The sort order to use when returning a list of videos or creators whose audience overlaps a particular list of videos. This parameter will default to sort descending by \"score\" if not specified. Refer to the AudienceOverlapSort documentation below for more details on available sort options.", "properties": {"sort_by": {"type": "string", "x-component": "select", "description": "Sort results by the given metric", "x-options": {"score": {"label": "Score", "description": "A blend of overlap and affinity scores, presented because usually the most \"interesting\" results have both high overlap and high affinity, and so sorting by this metric is recommended for most cases. High affinity and low overlap tends to reveal small, non-influential entities. High overlap and low affinity tends to reveal large channels that may not be tightly correlated with the source channels or videos."}, "affinity": {"label": "Affinity", "description": "We define this to be the \"increase in likelihood that a user is to be an audience member of the discovered entity given that he/she is in the audience of the source creators or videos\". This value is reciprocal, meaning that you also read that in the opposite direction (swapping \"discovered entity\" and \"source creators or videos\") and it holds true. Think of this as a correlation score. There is no upper bound on this value; higher values simply indicate a stronger correlation between the source creators or videos and the discovered entity."}, "overlap": {"label": "Overlap", "description": "The portion of the source audience that is also an audience member of the result (creator or video). Note that this portion is expressed over the range [0,1], so a value of 0.04 means 4%. Also be aware that in general, overlap numbers will be much smaller for video overlap queries, since audience sizes for individual videos are understandably smaller than those for overall channels."}}}}}, "limit": {"type": "integer", "description": "Limit the number of results. Default is 2000."}}}}}}, "responses": {"200": {"description": "Status of operation", "headers": {"Tubular-RateLimit-Overall-Limit": {"description": "The overall rate limit is 60 requests per minute. This rate limit applies to any combination of API methods that are called within a trailing 1-minute timeframe.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Overall-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Limit": {"description": "The concurrency rate limit is set to 1. This means that no more than a single request can be made at a time (i.e., in parallel). Attempting to issue a video.search request while a video.facets request is still running, for example will cause the video.search request to return a rate_limited error.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Remaining": {"description": "Number of concurrent requests available for use.", "schema": {"type": "integer"}}, "Tubular-Quota-Rows-Consumed": {"description": "Number of rows consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Consumed": {"description": "Number of quota units consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Limit": {"description": "Total quota units available for the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Remaining": {"description": "Number of quota units remaining in the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Expires-After": {"description": "Date and time when the current quota period ends.", "schema": {"type": "string", "format": "date-time"}}, "Tubular-RateLimit-AudienceOverlap-Limit": {"description": "Audience overlap queries are computationally expensive. Because of this, Tubular places a limit of no more than 1 audience overlap query per minute.", "schema": {"type": "integer"}}, "Tubular-RateLimit-AudienceOverlap-Remaining": {"description": "A number of aduence overlap calls left to be made within the minute timeframe.", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"type": "object", "properties": {"ok": {"type": "boolean", "description": "Standard API response for success/failure."}, "results": {"type": "array", "description": "A list of objects representing either creators or videos (depending on the type of overlap requested) also watched by audience members of the source IDs. Up to 2,000 results will be returned, sorted by the requested sort parameter.", "items": {"type": "object", "properties": {"affinity": {"type": "number", "format": "double", "description": "Defined as \"the increase in likelihood that a user is to be an audience member of the discovered entity given that he/she is in the audience of the source creators.\" This value is reciprocal, meaning that you can also read this definition in the opposite direction (i.e., swapping \"discovered entity\" and \"source creators\") and it will also hold true. This can be thought of as a correlation score. There is no upper bound on this value; higher values simply indicate a stronger correlation between the source creators and the discovered entity."}, "overlap": {"type": "number", "format": "double", "description": "The portion of the source audience that is also an audience member of the result (creator or video). Note that this portion is expressed over the range [0,1], so a value of 0.04 means 4%. Also be aware that, in general, overlap numbers will be much smaller for video overlap queries, since audience sizes for individual videos are understandably smaller than those for overall channels."}, "score": {"type": "number", "format": "double", "description": "A blend of overlap and affinity scores, presented because usually the most \"interesting\" results have both high overlap and high affinity. High affinity and low overlap tends to reveal small, non-influential entities. High overlap and low affinity tends to reveal large channels that may not be tightly correlated with the source creators."}, "creator_id": {"type": "string", "description": "The creator identifier associated with the overlap result (note that this will only be returned if the overlap type requested is of type \"creator\")."}, "video_id": {"type": "object", "description": "The video identifier associated with the overlap result (note that this will only be returned if the overlap type requested is of type \"video\").", "properties": {"platform": {"type": "string", "description": "The social platform for the video.", "x-options": {"youtube": "YouTube", "facebook": "Facebook", "instagram": "Instagram", "twitch": "Twitch"}}, "id": {"type": "string", "description": "A platform-specific unique identifier tied to the video. Typically, this identifier is also included by the social platform URL where a video can be viewed (e.g., the URL \"https://www.youtube.com/watch?v=abc123\" for video id \"abc123\" is used to refer to a YouTube video with that id)."}}}}}}}}}}}, "429": {"description": "The query is rate-limited.", "headers": {"Tubular-RateLimit-Overall-Limit": {"description": "The overall rate limit is 60 requests per minute. This rate limit applies to any combination of API methods that are called within a trailing 1-minute timeframe.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Overall-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Limit": {"description": "The concurrency rate limit is set to 1. This means that no more than a single request can be made at a time (i.e., in parallel). Attempting to issue a video.search request while a video.facets request is still running, for example will cause the video.search request to return a rate_limited error.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Remaining": {"description": "Number of concurrent requests available for use.", "schema": {"type": "integer"}}, "Tubular-Quota-Rows-Consumed": {"description": "Number of rows consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Consumed": {"description": "Number of quota units consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Limit": {"description": "Total quota units available for the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Remaining": {"description": "Number of quota units remaining in the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Expires-After": {"description": "Date and time when the current quota period ends.", "schema": {"type": "string", "format": "date-time"}}, "Tubular-RateLimit-AudienceOverlap-Limit": {"description": "Audience overlap queries are computationally expensive. Because of this, Tubular places a limit of no more than 1 audience overlap query per minute.", "schema": {"type": "integer"}}, "Tubular-RateLimit-AudienceOverlap-Remaining": {"description": "A number of aduence overlap calls left to be made within the minute timeframe.", "schema": {"type": "integer"}}}}}}}, "/creator.search": {"x-requires": ["api_intelligence"], "x-group": ["data", "creator"], "post": {"summary": "Returns a list of creator identifiers pertaining to a particular creator search query.", "parameters": [{"in": "header", "description": "Tubular API key.", "name": "Api-Key", "schema": {"type": "string"}}], "requestBody": {"content": {"application/json": {"schema": {"type": "object", "required": ["query", "fields"], "properties": {"query": {"type": "object", "description": "Defines search criteria that combines include and exclude filters.", "properties": {"savedsearch_id": {"type": "integer", "x-component": "select", "description": "Creator saved search id", "x-source": "qb/getCreatorSavedSearches"}, "include_filter": {"type": "object", "description": "A creator filter to be included by the query. Defaults to include everything if not specified.", "properties": {"search": {"type": "string", "description": "The search text string to be included in the filter for searching across creator names and themes. This string may include optional boolean search operators as described by the Help Center. Defaults to empty string if not specified.", "x-hint": "Use AND and OR operators", "x-placeholder": null}, "creators": {"type": "array", "x-component": "select", "x-autocomplete": "qb/searchCreators", "x-add": true, "description": "A list of one or more creator identifiers representing the creators that should be retrieved.", "items": {"type": "string"}}, "creator_types": {"type": "array", "description": "An array of creator types to use in the filter.", "x-component": "select", "x-options": {"influencer": "Influencer", "brand": "Brand", "media company": "Media Company", "aggregator": "Aggregator"}, "items": {"type": "string"}}, "creator_platforms": {"type": "array", "x-component": "select", "description": "An array of social platforms to use in the filter.", "x-options": {"youtube": "YouTube", "facebook": "Facebook", "instagram": "Instagram", "twitch": "Twitch", "tiktok": "TikTok"}, "items": {"type": "string"}}, "creator_genres": {"type": "array", "description": "An array of content genre identifiers to use in the filter. Available content genre identifiers can be obtained via a VideoFacets query. Defaults to all content genres if not specified.", "x-component": "select", "x-options": {"2": "Travel", "3": "Music & Dance", "4": "Sports", "5": "Animals & Pets", "7": "People & Blogs", "9": "Cars, Trucks & Racing", "11": "Business", "13": "Kids Entertainment & Animation", "14": "Education", "15": "Food & Drink", "16": "Fashion & Style", "19": "Health, Fitness & Self Help", "21": "Home & DIY", "22": "News & Politics", "23": "Beauty", "24": "Film & Movies", "27": "Gaming", "32": "Family & Parenting", "33": "Science & Tech", "36": "Entertainment", "37": "General Interest"}, "items": {"type": "integer"}}, "creator_countries": {"type": "array", "description": "Specifies the countries associated with the creator's accounts when limiting videos (e.g., only videos whose accounts are associated with the United States and France). Available creator countries can be obtained via a VideoFacets query. Country strings are represented as two-letter ISO 3166-1 alpha-2 codes. Defaults to all countries if not specified.", "items": {"type": "string"}, "x-component": "select", "x-autocomplete": "qb/getCountries"}, "creator_languages": {"type": "array", "description": "Specifies the dominant language of the creator to use in the filter. Languages are represented as ISO 639-1 two-letter language codes (for e.g. en, ja, es). Defaults to all languages if not specified.", "items": {"type": "string"}, "x-component": "select", "x-autocomplete": "qb/getLanguages"}, "creator_industries": {"type": "array", "description": "An array of creator industry identifiers to use in the filter. Defaults to all creator industries if not specified. Relevant for Brands.", "x-component": "select", "x-options": {"1": "Technology", "2": "Travel & Leisure", "3": "Music", "4": "CPG", "5": "Automotive", "6": "Financial & Insurance", "7": "Toys & Board Games", "8": "Media", "9": "Retail", "10": "Logistics & Heavy Industry", "11": "Other", "12": "Apparel & Accessories", "13": "Beverages", "14": "Personal Care & Health", "15": "Education", "16": "Public Service & Nonprofit", "17": "Food", "19": "Telecom", "20": "Pets", "21": "Sports Teams & Leagues", "22": "Gaming", "23": "Energy", "25": "Electronics", "27": "Broadcast, Cable, Radio, Film", "28": "Digital First Media", "29": "Magazine & Newspaper", "30": "Beauty"}, "items": {"type": "integer"}}, "creator_properties": {"type": "array", "x-component": "select", "description": "An array of creator property identifiers to use in the filter. Available creator properties can be obtained via a VideoFacets query. Defaults to all creator properties if not specified.", "x-autocomplete": "qb/searchProperties", "items": {"type": "integer"}}, "creator_list": {"type": "integer", "description": "A creator custom list identifier to use in the filter. A creator list represents a custom list of creators. These custom lists can be created and modified programmatically. See the Custom List section of the API documentation for more details. Available creator lists can be obtained via the custom_list.enumerate method. Defaults to not include a creator list.", "x-component": "select", "x-source": "qb/getCreatorLists"}, "creator_last_upload": {"type": "string", "x-component": "select", "description": "Applies a relative date filter to the number of days from the current day when a video was last uploaded by a creator. Note that the upload date is determined by the time in UTC that the video was uploaded. Defaults to all available data if not specified.", "x-options": {"last_7": "Last 7 days", "last_30": "Last 30 days", "last_90": "Last 90 days"}}, "creator_views": {"type": "object", "x-component": "integerRange", "description": "Applies a view limit (total number of views across all accounts for the previous month) to use in the filter. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "creator_rising_star": {"type": "boolean", "description": "Specifies whether to limit the filter to creators who are identified by Tubular as rising stars. If not specified, then all creators are included (i.e., both rising and non-rising stars)."}, "creator_facebook_watch": {"type": "boolean", "description": "Specifies whether to limit the filter to creators who publish a show on Facebook watch. If not specified, then all creators are included (i.e., both Facebook watch creators and non-Facebook watch creators.) Value can only be true or unspecified."}, "accounts": {"type": "array", "description": "Applies a filter limit to creators who meet the account-specific thresholds specified for a particular social platform. Defaults to all accounts if not specified.", "items": {"type": "object", "required": ["platform"], "properties": {"platform": {"type": "string", "x-component": "select", "description": "The platform name identifier associated with this account filter.", "x-options": {"youtube": "YouTube", "facebook": "Facebook", "instagram": "Instagram", "twitch": "Twitch", "tiktok": "TikTok"}}, "audience_min_male": {"type": "number", "format": "double", "description": "Applies a minimum threshold to creators whose platform audience is male. Specifying a value of 26.4, for example, means that a minimum of 26.4% of the platform audience for the creator must be male. This filter parameter is currently only available for the YouTube and Facebook platforms. Defaults to the full range if not specified."}, "audience_min_female": {"type": "number", "format": "double", "description": "Applies a minimum threshold to creators whose platform audience is female. Specifying a value of 32.1, for example, means that a minimum of 32.1% of the platform audience for the creator must be female. This filter parameter is currently only available for the YouTube and Facebook platforms. Defaults to the full range if not specified."}, "audience_age_range": {"type": "object", "description": "Applies an age range limit for the creator's platform audience to use in the filter. Note that only certain age values are currently allowed by the audience_age_range parameter. The allowable values include the following - 13, 18, 25, 35, 45, 55 Specifying either a min or max value for this parameter outside of the allowable values listed above will return an error. This filter parameter is currently only available for the YouTube and Facebook platforms. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "audience_min_age_range": {"type": "number", "format": "double", "description": "Applies a minimum threshold to the audience_age_range parameter. Specifying a value of 22.2 when audience_age_range is set to ages between 18 to 25, for example, means that a minimum of 22.2% of the platform audience for the creator must be between the ages of 18 to 25. Note that this parameter is intended to be used in conjunction with the audience_age_range parameter and will otherwise be ignored. This filter parameter is currently only supported for the YouTube and Facebook platforms. Defaults to the full range if not specified"}, "audience_locations": {"type": "array", "items": {"type": "object", "properties": {"country": {"type": "string", "description": "Specifies the country as a two-letter ISO 3166-1 alpha-2 code associated with this filter. Note that this parameter must be used in conjunction with the parameter and will otherwise be ignored. This filter parameter is currently only available for the Facebook and YouTube platforms.", "x-component": "select", "x-autocomplete": "qb/getCountries"}, "min": {"type": "number", "format": "double", "description": "Applies a minimum threshold to the parameter. Specifying a value of 20.5 when the parameter is set to \"de\", for example, means that a minimum of 20.5% of the platform audience for the creator must be located in Germany. Note that this parameter must be used in conjunction with the parameter and will otherwise be ignored. This filter parameter is currently only available for the Facebook and YouTube platforms."}}}}, "followers": {"type": "object", "description": "Applies a follower, subscriber (in the case of YouTube) or Facebook page like a range limit for the creator's platform account to use in the filter. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "views": {"type": "object", "description": "Applies a views range limit for the creator's platform account to use in the filter. This filter parameter is currently only available for the Facebook, Instagram, and YouTube platforms. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "monthly_views": {"type": "object", "description": "Applies the last month views range limit for the creator's platform account to use in the filter. This filter parameter is currently only available for all platforms except Twitch. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "v30": {"type": "object", "description": "Applies a v30 range limit for the creator's platform account to use in the filter. Refer to Tubular Video Ratings documentation for details on how v30 is calculated. This filter parameter is currently only available for the Facebook, Tiktok, Instagram, and YouTube platforms. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}}}}}}, "exclude_filter": {"type": "object", "description": "A creator filter to be excluded by the query. Defaults to exclude no videos if not specified.", "properties": {"search": {"type": "string", "description": "The search text string to be included in the filter for searching across creator names and themes. This string may include optional boolean search operators as described by the Help Center. Defaults to empty string if not specified.", "x-hint": "Use AND and OR operators", "x-placeholder": null}, "creators": {"type": "array", "x-component": "select", "x-autocomplete": "qb/searchCreators", "x-add": true, "description": "A list of one or more creator identifiers representing the creators that should be retrieved.", "items": {"type": "string"}}, "creator_types": {"type": "array", "description": "An array of creator types to use in the filter.", "x-component": "select", "x-options": {"influencer": "Influencer", "brand": "Brand", "media company": "Media Company", "aggregator": "Aggregator"}, "items": {"type": "string"}}, "creator_platforms": {"type": "array", "x-component": "select", "description": "An array of social platforms to use in the filter.", "x-options": {"youtube": "YouTube", "facebook": "Facebook", "instagram": "Instagram", "twitch": "Twitch", "tiktok": "TikTok"}, "items": {"type": "string"}}, "creator_genres": {"type": "array", "description": "An array of content genre identifiers to use in the filter. Available content genre identifiers can be obtained via a VideoFacets query. Defaults to all content genres if not specified.", "x-component": "select", "x-options": {"2": "Travel", "3": "Music & Dance", "4": "Sports", "5": "Animals & Pets", "7": "People & Blogs", "9": "Cars, Trucks & Racing", "11": "Business", "13": "Kids Entertainment & Animation", "14": "Education", "15": "Food & Drink", "16": "Fashion & Style", "19": "Health, Fitness & Self Help", "21": "Home & DIY", "22": "News & Politics", "23": "Beauty", "24": "Film & Movies", "27": "Gaming", "32": "Family & Parenting", "33": "Science & Tech", "36": "Entertainment", "37": "General Interest"}, "items": {"type": "integer"}}, "creator_countries": {"type": "array", "description": "Specifies the countries associated with the creator's accounts when limiting videos (e.g., only videos whose accounts are associated with the United States and France). Available creator countries can be obtained via a VideoFacets query. Country strings are represented as two-letter ISO 3166-1 alpha-2 codes. Defaults to all countries if not specified.", "items": {"type": "string"}, "x-component": "select", "x-autocomplete": "qb/getCountries"}, "creator_languages": {"type": "array", "description": "Specifies the dominant language of the creator to use in the filter. Languages are represented as ISO 639-1 two-letter language codes (for e.g. en, ja, es). Defaults to all languages if not specified.", "items": {"type": "string"}, "x-component": "select", "x-autocomplete": "qb/getLanguages"}, "creator_industries": {"type": "array", "description": "An array of creator industry identifiers to use in the filter. Defaults to all creator industries if not specified. Relevant for Brands.", "x-component": "select", "x-options": {"1": "Technology", "2": "Travel & Leisure", "3": "Music", "4": "CPG", "5": "Automotive", "6": "Financial & Insurance", "7": "Toys & Board Games", "8": "Media", "9": "Retail", "10": "Logistics & Heavy Industry", "11": "Other", "12": "Apparel & Accessories", "13": "Beverages", "14": "Personal Care & Health", "15": "Education", "16": "Public Service & Nonprofit", "17": "Food", "19": "Telecom", "20": "Pets", "21": "Sports Teams & Leagues", "22": "Gaming", "23": "Energy", "25": "Electronics", "27": "Broadcast, Cable, Radio, Film", "28": "Digital First Media", "29": "Magazine & Newspaper", "30": "Beauty"}, "items": {"type": "integer"}}, "creator_properties": {"type": "array", "x-component": "select", "description": "An array of creator property identifiers to use in the filter. Available creator properties can be obtained via a VideoFacets query. Defaults to all creator properties if not specified.", "x-autocomplete": "qb/searchProperties", "items": {"type": "integer"}}, "creator_list": {"type": "integer", "description": "A creator custom list identifier to use in the filter. A creator list represents a custom list of creators. These custom lists can be created and modified programmatically. See the Custom List section of the API documentation for more details. Available creator lists can be obtained via the custom_list.enumerate method. Defaults to not include a creator list.", "x-component": "select", "x-source": "qb/getCreatorLists"}, "creator_last_upload": {"type": "string", "x-component": "select", "description": "Applies a relative date filter to the number of days from the current day when a video was last uploaded by a creator. Note that the upload date is determined by the time in UTC that the video was uploaded. Defaults to all available data if not specified.", "x-options": {"last_7": "Last 7 days", "last_30": "Last 30 days", "last_90": "Last 90 days"}}, "creator_views": {"type": "object", "x-component": "integerRange", "description": "Applies a view limit (total number of views across all accounts for the previous month) to use in the filter. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "creator_rising_star": {"type": "boolean", "description": "Specifies whether to limit the filter to creators who are identified by Tubular as rising stars. If not specified, then all creators are included (i.e., both rising and non-rising stars)."}, "creator_facebook_watch": {"type": "boolean", "description": "Specifies whether to limit the filter to creators who publish a show on Facebook watch. If not specified, then all creators are included (i.e., both Facebook watch creators and non-Facebook watch creators.) Value can only be true or unspecified."}, "accounts": {"type": "array", "description": "Applies a filter limit to creators who meet the account-specific thresholds specified for a particular social platform. Defaults to all accounts if not specified.", "items": {"type": "object", "required": ["platform"], "properties": {"platform": {"type": "string", "x-component": "select", "description": "The platform name identifier associated with this account filter.", "x-options": {"youtube": "YouTube", "facebook": "Facebook", "instagram": "Instagram", "twitch": "Twitch", "tiktok": "TikTok"}}, "audience_min_male": {"type": "number", "format": "double", "description": "Applies a minimum threshold to creators whose platform audience is male. Specifying a value of 26.4, for example, means that a minimum of 26.4% of the platform audience for the creator must be male. This filter parameter is currently only available for the YouTube and Facebook platforms. Defaults to the full range if not specified."}, "audience_min_female": {"type": "number", "format": "double", "description": "Applies a minimum threshold to creators whose platform audience is female. Specifying a value of 32.1, for example, means that a minimum of 32.1% of the platform audience for the creator must be female. This filter parameter is currently only available for the YouTube and Facebook platforms. Defaults to the full range if not specified."}, "audience_age_range": {"type": "object", "description": "Applies an age range limit for the creator's platform audience to use in the filter. Note that only certain age values are currently allowed by the audience_age_range parameter. The allowable values include the following - 13, 18, 25, 35, 45, 55 Specifying either a min or max value for this parameter outside of the allowable values listed above will return an error. This filter parameter is currently only available for the YouTube and Facebook platforms. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "audience_min_age_range": {"type": "number", "format": "double", "description": "Applies a minimum threshold to the audience_age_range parameter. Specifying a value of 22.2 when audience_age_range is set to ages between 18 to 25, for example, means that a minimum of 22.2% of the platform audience for the creator must be between the ages of 18 to 25. Note that this parameter is intended to be used in conjunction with the audience_age_range parameter and will otherwise be ignored. This filter parameter is currently only supported for the YouTube and Facebook platforms. Defaults to the full range if not specified"}, "audience_locations": {"type": "array", "items": {"type": "object", "properties": {"country": {"type": "string", "description": "Specifies the country as a two-letter ISO 3166-1 alpha-2 code associated with this filter. Note that this parameter must be used in conjunction with the parameter and will otherwise be ignored. This filter parameter is currently only available for the Facebook and YouTube platforms.", "x-component": "select", "x-autocomplete": "qb/getCountries"}, "min": {"type": "number", "format": "double", "description": "Applies a minimum threshold to the parameter. Specifying a value of 20.5 when the parameter is set to \"de\", for example, means that a minimum of 20.5% of the platform audience for the creator must be located in Germany. Note that this parameter must be used in conjunction with the parameter and will otherwise be ignored. This filter parameter is currently only available for the Facebook and YouTube platforms."}}}}, "followers": {"type": "object", "description": "Applies a follower, subscriber (in the case of YouTube) or Facebook page like a range limit for the creator's platform account to use in the filter. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "views": {"type": "object", "description": "Applies a views range limit for the creator's platform account to use in the filter. This filter parameter is currently only available for the Facebook, Instagram, and YouTube platforms. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "monthly_views": {"type": "object", "description": "Applies the last month views range limit for the creator's platform account to use in the filter. This filter parameter is currently only available for all platforms except Twitch. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "v30": {"type": "object", "description": "Applies a v30 range limit for the creator's platform account to use in the filter. Refer to Tubular Video Ratings documentation for details on how v30 is calculated. This filter parameter is currently only available for the Facebook, Tiktok, Instagram, and YouTube platforms. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}}}}}}}}, "fields": {"type": "array", "x-component": "select", "items": {"type": "string"}, "x-options": {"creator_id": {"label": "Creator ID", "description": "Creator identifier for a particular creator."}, "title": {"label": "Creator Title", "description": "The title of the creator."}, "description": {"label": "Creator Description", "description": "The description of the creator."}, "thumbnail_url": {"label": "Thumbnail url", "description": "The URL of the thumbnail image for this creator."}, "type": {"label": "Creator Type", "description": "The type of creator."}, "country": {"label": "Country", "description": "The two-letter ISO 3166-1 alpha-2 country code associated with the creator."}, "language": {"label": "Creator Language", "description": "The ISO 639-1 two-letter language code associated with the dominant language of the creator."}, "genre": {"label": "Creator Genre", "description": "The content category associated with the creator"}, "industry": {"label": "Creator Industry", "description": "The industry associated with the creator."}, "properties": {"label": "Creator Properties", "description": "Parent properties associated with this creator."}, "direct_property": {"label": "Direct Property", "description": "A direct property associated with this creator."}, "uploads_90d": {"label": "Last 90d uploads", "description": "A total number of video uploads by this creator within the last 90 days."}, "views": {"label": "Total Views", "description": "Total views across all accounts for the creator."}, "last_upload_date": {"label": "Last Upload Date", "description": "The date a video was last uploaded by the creator in \"YYYY-MM-DD\" format. Note that the upload date is determined by the time in UTC that the video was uploaded."}, "accounts.thumbnail_url": {"label": "Account Thumbnail URL", "description": "The URL of the thumbnail image for an account."}, "accounts.title": {"label": "Account Title", "description": "The title of the account."}, "accounts.account_url": {"label": "Account URL", "description": "The URL for an account."}, "accounts.platform": {"label": "Account Platform", "description": "The social platform associated with an account."}, "accounts.category": {"label": "Account Category", "description": "The content category associated with an account."}, "accounts.description": {"label": "Account Description", "description": "The description associated with an account."}, "accounts.gid": {"label": "Account Tubular GID", "description": null}, "accounts.30d_followers": {"label": "Account 30d followers", "description": "A number of YouTube subscribers, Facebook page likes or followers for all other platforms that have been gained within the last 30 days."}, "accounts.30d_followers_growth": {"label": "Account 30d followers growth", "description": "Percentage of overall subscribers/page likes/followers that have grown within the last 30 days."}, "accounts.followers": {"label": "Account followers", "description": null}, "accounts.influencer_score": {"label": "Account Influencer Score", "description": "An account's influencer score (currently only available for the YouTube platform)."}, "accounts.views": {"label": "Account total views", "description": "Total views over time for an account."}, "accounts.monthly_views": {"label": "Account Last Month Views", "description": "Total views for an account for the previous month."}, "accounts.monthly_views_growth": {"label": "Account monthly views growth", "description": "Percentage of views growth for the previous month (Monthly Views / Total Views)"}, "accounts.monthly_v30": {"label": "Account last month V30", "description": "The v30 across all videos for an account for the previous month."}, "accounts.monthly_er30": {"label": "Account last month ER30", "description": "The er30 across all videos for an account for the previous month."}, "accounts.audience_ages": {"label": "Account audience ages", "description": "An array of objects representing audience age ranges for a particular account."}, "accounts.audience_locations": {"label": "Account audience locations", "description": "An array of objects representing the audience locations for a particular account."}, "accounts.audience_genders": {"label": "Account audience genders", "description": "An array of objects representing the audience genders for a particular account."}}}, "sort": {"type": "object", "description": "A JSON string representation of sort-related parameters that are used to determine the order by which creator results are returned. Note that this property only needs to be specified for the initial query. This parameter will be ignored for subsequent scroll requests.", "properties": {"sort": {"type": "string", "description": "A metric to sort creators by. Defaults to \"monthly_views\" if not specified.", "x-component": "select", "x-options": {"monthly_views": {"label": "Last Month Views", "description": "Sort by views across all platforms for the previous month"}, "youtube.uploads": {"label": "YouTube uploads", "description": "Sort by total YouTube uploads"}, "youtube.views": {"label": "Total YouTube views", "description": "Sort by total YouTube views"}, "youtube.subscribers": {"label": "YouTube subscribers", "description": "Sort by total YouTube subscribers"}, "youtube.monthly_views": {"label": "YouTube monthly views", "description": "Sort by YouTube views for the previous month"}, "youtube.monthly_views_growth": {"label": "YouTube subscribers", "description": "Sort by YouTube percentage of views growth for the previous month (Monthly Views / Total Views)"}, "youtube.monthly_v30": {"label": "YouTube monthly V30", "description": "Sort by YouTube v30 for the previous month"}, "youtube.monthly_er30": {"label": "YouTube montly ER30", "description": "Sort by YouTube er30 for the previous month"}, "youtube.30d_subscribers": {"label": "YouTube 30d subscribers", "description": "Sort by YouTube 30 day subscribers"}, "youtube.30d_subscribers_growth": {"label": "YouTube 30 day subscribers growth", "description": "Sort by YouTube percentage of subscriber growth in the last 30 days (30 day Subscribers / Total Subscribers)"}, "youtube.influencer_score": {"label": "YouTube subscribers", "description": "Sort by YouTube influencer score"}, "facebook.uploads": {"label": "Facebook uploads", "description": "Sort by total Facebook uploads"}, "facebook.page_likes": {"label": "Facebook page likes", "description": "Sort by total Facebook page likes"}, "facebook.views": {"label": "Facebook views", "description": "Sort by total lifetime Facebook views"}, "facebook.monthly_views": {"label": "Facebook monthly views", "description": "Sort by Facebook views for the previous month"}, "facebook.monthly_views_growth": {"label": "Facebook monthly views growth", "description": "Sort by Facebook percentage of views growth for the previous month (Monthly Views / Total Views)"}, "facebook.monthly_v30": {"label": "Facebook V30", "description": "Sort by Facebook v30 for the previous month"}, "facebook.monthly_er30": {"label": "Facebook ER30", "description": "Sort by Facebook er30 for the previous month"}, "facebook.30d_page_likes": {"label": "Facebook 30d page likes", "description": "Sort by Facebook page_likes in the last 30 days"}, "facebook.30d_followers": {"label": "Facebook 30d followers", "description": "Sort by Facebook page_likes in the last 30 days (same as \"facebook.30d_page_likes\")"}, "facebook.30d_page_likes_growth": {"label": "Facebook 30d page likes growth", "description": "Sort by Facebook percentage of page likes growth in the last 30 days (30 day Page Likes / Total Page Likes)"}, "instagram.uploads": {"label": "Instagram uploads", "description": "Sort by total Instagram uploads"}, "instagram.followers": {"label": "Instagram followers", "description": "Sort by total Instagram followers"}, "instagram.views": {"label": "Instagram views", "description": "Sort by total lifetime Instagram views"}, "instagram.monthly_views": {"label": "Instagram monthly views", "description": "Sort by total Instagram views for the previous month"}, "instagram.monthly_views_growth": {"label": "Instagram monthly views growth", "description": "Sort by Instagram percentage of views growth for the previous month (Monthly Views / Total Views)"}, "instagram.monthly_v30": {"label": "Instagram V30", "description": "Sort by Instagram v30 for the previous month"}, "instagram.monthly_er30": {"label": "Instagram ER30", "description": "Sort by Instagram er30 for the previous month"}, "instagram.30d_followers": {"label": "Instagram 30d followers", "description": "Sort by Instagram followers in the last 30 days"}, "instagram.30d_followers_growth": {"label": "Instagram 30d followers growth", "description": "Sort by Instagram follower growth in the last 30 days (30 day Followers / Total Followers)"}, "twitch.views": {"label": "Twitch views", "description": "Sort by total lifetime Twitch views"}, "twitch.followers": {"label": "Twitch followers", "description": "Sort by total Twitch followers"}, "twitch.30d_followers": {"label": "Twitch 30d followers", "description": "Sort by Twitch followers in the last 30 days"}, "twitch.30d_followers_growth": {"label": "Twitch 30d followers growth", "description": "Sort by Twitch follower growth in the last 30 days (30 day Followers / Total Followers)"}}}, "sort_reverse": {"type": "boolean", "description": "Specifies whether to sort search results in ascending (sort_reverse=False) or descending (sort_reverse=True) order. This parameter will default to ascending (sort_reverse=False) if not specified."}}}, "scroll": {"type": "object", "description": "A JSON string representation of the scroll window to use. This should only be set after an initial query has been performed in order to page through results.", "properties": {"scroll_token": {"type": "string", "description": "A unique id associated with the current query for which results are being retrieved. Note that the scroll token will expire if not used within 1 minute."}, "scroll_size": {"type": "integer", "description": "The maximum number of results to include for each window of results. Subsequent requests to creator.search or video.search will retrieve another ScrollWindow.scroll_size results. This parameter will default to 50 if not specified. The maximum scroll window size is 200."}}}}}}}}, "responses": {"200": {"description": "Status of operation", "headers": {"Tubular-RateLimit-Overall-Limit": {"description": "The overall rate limit is 60 requests per minute. This rate limit applies to any combination of API methods that are called within a trailing 1-minute timeframe.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Overall-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Limit": {"description": "The concurrency rate limit is set to 1. This means that no more than a single request can be made at a time (i.e., in parallel). Attempting to issue a video.search request while a video.facets request is still running, for example will cause the video.search request to return a rate_limited error.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Remaining": {"description": "Number of concurrent requests available for use.", "schema": {"type": "integer"}}, "Tubular-Quota-Rows-Consumed": {"description": "Number of rows consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Consumed": {"description": "Number of quota units consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Limit": {"description": "Total quota units available for the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Remaining": {"description": "Number of quota units remaining in the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Expires-After": {"description": "Date and time when the current quota period ends.", "schema": {"type": "string", "format": "date-time"}}, "Tubular-RateLimit-UniqueCreatorLimit-Limit": {"description": "Defines the total number of unique creators a client can retrieve in the current month.", "schema": {"type": "integer"}}, "Tubular-RateLimit-UniqueCreatorLimit-Remaining": {"description": "A number of unique creators left in this month.", "schema": {"type": "integer"}}, "Tubular-RateLimit-UniqueCreatorLimit-ExpiresAfter": {"description": "Specifies the date when the quota resets. Usually a beginning of each month.", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"type": "object", "properties": {"ok": {"type": "boolean", "description": "Standard API response for success/failure."}, "total": {"type": "integer", "description": "A total number of creators found."}, "creator_ids": {"type": "array", "items": {"type": "string"}, "description": "A list of creator identifiers matching the search query. A creator identifier is guaranteed to be globally unique (i.e., no two creators will ever use the same id). You can use a creator.details query to gather more information about a specific creator."}, "creators": {"type": "array", "description": "A list of JSON objects representing details for creators matching the search query. This field is populated only when fields parameter is specified.", "items": {"type": "object", "properties": {"creator_id": {"type": "string", "description": "Creator identifier for a particular creator. A creator id is guaranteed to be globally unique (i.e., no two creators will ever use the same id). You can use a creator.details query to gather more information about a specific creator."}, "title": {"type": "string", "description": "The title of the creator."}, "description": {"type": "string", "description": "The description of the creator."}, "thumbnail_url": {"type": "string", "description": "The URL of the thumbnail image for this creator."}, "type": {"type": "string", "description": "The type of creator."}, "country": {"type": "string", "description": "The two-letter ISO 3166-1 alpha-2 country code associated with the creator."}, "language": {"type": "string", "description": "The ISO 639-1 two-letter language code associated with the dominant language of the creator."}, "genre": {"type": "object", "description": "The content category associated with the creator", "properties": {"id": {"type": "integer", "description": "The identifier associated with a content category."}, "title": {"type": "string", "description": "The title associated with a content category."}}}, "industry": {"type": "object", "description": "The industry associated with the creator.", "properties": {"id": {"type": "integer", "description": "The unique identifier associated with the current industry."}, "title": {"type": "string", "description": "The title of the current industry."}}}, "properties": {"type": "array", "description": "An array of JSON objects representing the parent properties associated with this creator. Note that a single creator can have a series of parent properties associated with it, which Tubular stores as a hierarchical parent-child relationship. This property parameter represents all ancestors of a like the range parent hierarchy.", "items": {"type": "object", "properties": {"id": {"type": "integer", "description": "The unique identifier associated with the current property."}, "title": {"type": "string", "description": "The title of the current property."}}}}, "direct_property": {"type": "object", "description": "Direct property a creator is assiciated with.", "properties": {"id": {"type": "integer", "description": "The unique identifier associated with the property."}, "title": {"type": "string", "description": "The title of the property."}}}, "views": {"type": "integer", "description": "Total views across all accounts for the creator."}, "uploads_90d": {"type": "integer", "description": "A total number of video uploads by this creator within the last 90 days."}, "last_upload_date": {"type": "string", "description": "The date a video was last uploaded by the creator in \"YYYY-MM-DD\" format. Note that the upload date is determined by the time in UTC that the video was uploaded."}, "accounts": {"type": "array", "description": "A list of JSON string objects representing the social accounts for the current creator. Each object represents an account from a different social platform.", "items": {"type": "object", "properties": {"platform": {"type": "string", "description": "The social platform associated with an account."}, "title": {"type": "string", "description": "The title of the account."}, "description": {"type": "string", "description": "The description associated with an account."}, "account_url": {"type": "string", "description": "The URL for an account."}, "thumbnail_url": {"type": "string", "description": "The URL of the thumbnail image for an account."}, "views": {"type": "integer", "description": "Total views over time for an account."}, "followers": {"type": "integer", "description": "Total subscribers for a YouTube account, page likes for Facebook or total followers for all other platforms."}, "monthly_stats": {"type": "object", "description": "Monthly stats for an account.", "properties": {"views": {"type": "object", "description": "Historical monthly views.", "properties": {"month": {"type": "string", "description": "A calendar month value is attributed to."}, "value": {"type": "integer", "description": "The metric value for the given month."}}}}}, "monthly_views": {"type": "integer", "description": "Total views for an account for the previous month."}, "monthly_demographic_views": {"type": "array", "description": "Demographic stats for the latest month if was requested (see \"Creator Search\" section). It shows summarized views for requested set of locations calculated only for the last full month.", "items": {"type": "object", "properties": {"countries": {"type": "array", "description": "list of country codes (ISO 3166-1 alpha-2 country code)", "items": {"type": "string"}}, "views": {"type": "integer", "description": "Total amount of views calculated for the specified countries for the last month Currently this data can be returned only for YouTube accounts"}}}}, "monthly_views_growth": {"type": "number", "format": "double", "description": "Percentage of views growth for the previous month (Monthly Views / Total Views)"}, "monthly_v30": {"type": "integer", "description": "The v30 across all videos for an account for the previous month. Refer to Tubular Video Ratings documentation for details on how v30 is calculated."}, "monthly_er30": {"type": "integer", "description": "The er30 across all videos for an account for the previous month. Refer to Tubular Video Ratings documentation for details on how v30 is calculated."}, "30d_followers": {"type": "integer", "description": "A number of YouTube subscribers, Facebook page likes or followers for all other platforms that have been gained within the last 30 days. This parameter is available for Facebook, TikTok, Instagram, and YouTube platforms. A null value will be returned for all other platforms."}, "30d_followers_growth": {"type": "number", "format": "double", "description": "Percentage of overall subscribers/page likes/followers that have grown within the last 30 days. This parameter is available for Facebook, TikTok, Instagram, and YouTube platforms. A null value will be returned for all other platforms."}, "influencer_score": {"type": "number", "format": "double", "description": "An account's influencer score. More information about how influencer scores are calculated can be found in Tubular's Help Center documentation. This parameter is currently only available for the YouTube platform. A null value will be returned for all other platforms."}, "category": {"type": "object", "description": "The content category associated with an account.", "properties": {"id": {"type": "integer", "description": "The identifier associated with a content category."}, "title": {"type": "string", "description": "The title associated with a content category."}}}, "audience_ages": {"type": "array", "description": "An array of JSON objects representing audience age ranges for a particular account. This is currently only available for the YouTube platform.", "items": {"type": "object", "properties": {"range": {"type": "string", "description": "A particular age range represented by a string formatted as \"ages_X_Y\", where X is the minimum value in the range and Y is the maximum value in the range. A minimum value of 18 and a maximum value of 24 represents an age range between the age of 18 to 24."}, "value": {"type": "number", "format": "double", "description": "The percentage value assigned to the associated age range. A value of 22.2, for example, means that 22.2% of the platform audience was associated with the current audience_ages.range age range."}}}}, "audience_locations": {"type": "array", "description": "An array of JSON objects representing the audience locations for a particular account. This is currently only available for the YouTube and Facebook platforms.", "items": {"type": "object", "properties": {"country": {"type": "string", "description": "The two-letter ISO 3166-1 alpha-2 country code associated with the current location."}, "value": {"type": "number", "format": "double", "description": "The percentage value assigned to the associated country. A value of 32.2, for example, means that 32.2% of the platform audience was associated with the current audience_locations.country location."}}}}, "audience_genders": {"type": "array", "description": "An array of JSON objects representing the audience genders for a particular account.", "items": {"type": "object", "properties": {"gender": {"type": "string", "description": "Gender type, possible values \"male\", \"female\""}, "value": {"type": "number", "format": "double", "description": "Percentage in the audience of the specified gender type"}}}}, "audience_last_updated": {"type": "string", "description": "The date that audience data was last updated."}}}}}}}, "sort_month": {"type": "string", "description": "The month in \"YYYY-MM\" format that is used for sorting search results for the monthly sort options found in the sort parameter. Note that this parameter won't be provided for results that are not sorted using a monthly metric."}}}}}}, "429": {"description": "The query is rate-limited.", "headers": {"Tubular-RateLimit-Overall-Limit": {"description": "The overall rate limit is 60 requests per minute. This rate limit applies to any combination of API methods that are called within a trailing 1-minute timeframe.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Overall-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Limit": {"description": "The concurrency rate limit is set to 1. This means that no more than a single request can be made at a time (i.e., in parallel). Attempting to issue a video.search request while a video.facets request is still running, for example will cause the video.search request to return a rate_limited error.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Remaining": {"description": "Number of concurrent requests available for use.", "schema": {"type": "integer"}}, "Tubular-Quota-Rows-Consumed": {"description": "Number of rows consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Consumed": {"description": "Number of quota units consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Limit": {"description": "Total quota units available for the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Remaining": {"description": "Number of quota units remaining in the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Expires-After": {"description": "Date and time when the current quota period ends.", "schema": {"type": "string", "format": "date-time"}}, "Tubular-RateLimit-UniqueCreatorLimit-Limit": {"description": "Defines the total number of unique creators a client can retrieve in the current month.", "schema": {"type": "integer"}}, "Tubular-RateLimit-UniqueCreatorLimit-Remaining": {"description": "A number of unique creators left in this month.", "schema": {"type": "integer"}}, "Tubular-RateLimit-UniqueCreatorLimit-ExpiresAfter": {"description": "Specifies the date when the quota resets. Usually a beginning of each month.", "schema": {"type": "integer"}}}}}}}, "/creator.monthly_trends": {"x-requires": ["api_intelligence"], "x-group": ["data", "creator"], "post": {"summary": "Get per-platform monthly stats for a given creator search.", "parameters": [{"in": "header", "description": "Tubular API key.", "name": "Api-Key", "schema": {"type": "string"}}], "requestBody": {"content": {"application/json": {"schema": {"type": "object", "required": ["query"], "properties": {"query": {"type": "object", "description": "Defines search criteria that combines include and exclude filters.", "properties": {"savedsearch_id": {"type": "integer", "x-component": "select", "description": "Creator saved search id", "x-source": "qb/getCreatorSavedSearches"}, "include_filter": {"type": "object", "description": "A creator filter to be included by the query. Defaults to include everything if not specified.", "properties": {"search": {"type": "string", "description": "The search text string to be included in the filter for searching across creator names and themes. This string may include optional boolean search operators as described by the Help Center. Defaults to empty string if not specified.", "x-hint": "Use AND and OR operators", "x-placeholder": null}, "creators": {"type": "array", "x-component": "select", "x-autocomplete": "qb/searchCreators", "x-add": true, "description": "A list of one or more creator identifiers representing the creators that should be retrieved.", "items": {"type": "string"}}, "creator_types": {"type": "array", "description": "An array of creator types to use in the filter.", "x-component": "select", "x-options": {"influencer": "Influencer", "brand": "Brand", "media company": "Media Company", "aggregator": "Aggregator"}, "items": {"type": "string"}}, "creator_platforms": {"type": "array", "x-component": "select", "description": "An array of social platforms to use in the filter.", "x-options": {"youtube": "YouTube", "facebook": "Facebook", "instagram": "Instagram", "twitch": "Twitch", "tiktok": "TikTok"}, "items": {"type": "string"}}, "creator_genres": {"type": "array", "description": "An array of content genre identifiers to use in the filter. Available content genre identifiers can be obtained via a VideoFacets query. Defaults to all content genres if not specified.", "x-component": "select", "x-options": {"2": "Travel", "3": "Music & Dance", "4": "Sports", "5": "Animals & Pets", "7": "People & Blogs", "9": "Cars, Trucks & Racing", "11": "Business", "13": "Kids Entertainment & Animation", "14": "Education", "15": "Food & Drink", "16": "Fashion & Style", "19": "Health, Fitness & Self Help", "21": "Home & DIY", "22": "News & Politics", "23": "Beauty", "24": "Film & Movies", "27": "Gaming", "32": "Family & Parenting", "33": "Science & Tech", "36": "Entertainment", "37": "General Interest"}, "items": {"type": "integer"}}, "creator_countries": {"type": "array", "description": "Specifies the countries associated with the creator's accounts when limiting videos (e.g., only videos whose accounts are associated with the United States and France). Available creator countries can be obtained via a VideoFacets query. Country strings are represented as two-letter ISO 3166-1 alpha-2 codes. Defaults to all countries if not specified.", "items": {"type": "string"}, "x-component": "select", "x-autocomplete": "qb/getCountries"}, "creator_languages": {"type": "array", "description": "Specifies the dominant language of the creator to use in the filter. Languages are represented as ISO 639-1 two-letter language codes (for e.g. en, ja, es). Defaults to all languages if not specified.", "items": {"type": "string"}, "x-component": "select", "x-autocomplete": "qb/getLanguages"}, "creator_industries": {"type": "array", "description": "An array of creator industry identifiers to use in the filter. Defaults to all creator industries if not specified. Relevant for Brands.", "x-component": "select", "x-options": {"1": "Technology", "2": "Travel & Leisure", "3": "Music", "4": "CPG", "5": "Automotive", "6": "Financial & Insurance", "7": "Toys & Board Games", "8": "Media", "9": "Retail", "10": "Logistics & Heavy Industry", "11": "Other", "12": "Apparel & Accessories", "13": "Beverages", "14": "Personal Care & Health", "15": "Education", "16": "Public Service & Nonprofit", "17": "Food", "19": "Telecom", "20": "Pets", "21": "Sports Teams & Leagues", "22": "Gaming", "23": "Energy", "25": "Electronics", "27": "Broadcast, Cable, Radio, Film", "28": "Digital First Media", "29": "Magazine & Newspaper", "30": "Beauty"}, "items": {"type": "integer"}}, "creator_properties": {"type": "array", "x-component": "select", "description": "An array of creator property identifiers to use in the filter. Available creator properties can be obtained via a VideoFacets query. Defaults to all creator properties if not specified.", "x-autocomplete": "qb/searchProperties", "items": {"type": "integer"}}, "creator_list": {"type": "integer", "description": "A creator custom list identifier to use in the filter. A creator list represents a custom list of creators. These custom lists can be created and modified programmatically. See the Custom List section of the API documentation for more details. Available creator lists can be obtained via the custom_list.enumerate method. Defaults to not include a creator list.", "x-component": "select", "x-source": "qb/getCreatorLists"}, "creator_last_upload": {"type": "string", "x-component": "select", "description": "Applies a relative date filter to the number of days from the current day when a video was last uploaded by a creator. Note that the upload date is determined by the time in UTC that the video was uploaded. Defaults to all available data if not specified.", "x-options": {"last_7": "Last 7 days", "last_30": "Last 30 days", "last_90": "Last 90 days"}}, "creator_views": {"type": "object", "x-component": "integerRange", "description": "Applies a view limit (total number of views across all accounts for the previous month) to use in the filter. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "creator_rising_star": {"type": "boolean", "description": "Specifies whether to limit the filter to creators who are identified by Tubular as rising stars. If not specified, then all creators are included (i.e., both rising and non-rising stars)."}, "creator_facebook_watch": {"type": "boolean", "description": "Specifies whether to limit the filter to creators who publish a show on Facebook watch. If not specified, then all creators are included (i.e., both Facebook watch creators and non-Facebook watch creators.) Value can only be true or unspecified."}, "accounts": {"type": "array", "description": "Applies a filter limit to creators who meet the account-specific thresholds specified for a particular social platform. Defaults to all accounts if not specified.", "items": {"type": "object", "required": ["platform"], "properties": {"platform": {"type": "string", "x-component": "select", "description": "The platform name identifier associated with this account filter.", "x-options": {"youtube": "YouTube", "facebook": "Facebook", "instagram": "Instagram", "twitch": "Twitch", "tiktok": "TikTok"}}, "audience_min_male": {"type": "number", "format": "double", "description": "Applies a minimum threshold to creators whose platform audience is male. Specifying a value of 26.4, for example, means that a minimum of 26.4% of the platform audience for the creator must be male. This filter parameter is currently only available for the YouTube and Facebook platforms. Defaults to the full range if not specified."}, "audience_min_female": {"type": "number", "format": "double", "description": "Applies a minimum threshold to creators whose platform audience is female. Specifying a value of 32.1, for example, means that a minimum of 32.1% of the platform audience for the creator must be female. This filter parameter is currently only available for the YouTube and Facebook platforms. Defaults to the full range if not specified."}, "audience_age_range": {"type": "object", "description": "Applies an age range limit for the creator's platform audience to use in the filter. Note that only certain age values are currently allowed by the audience_age_range parameter. The allowable values include the following - 13, 18, 25, 35, 45, 55 Specifying either a min or max value for this parameter outside of the allowable values listed above will return an error. This filter parameter is currently only available for the YouTube and Facebook platforms. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "audience_min_age_range": {"type": "number", "format": "double", "description": "Applies a minimum threshold to the audience_age_range parameter. Specifying a value of 22.2 when audience_age_range is set to ages between 18 to 25, for example, means that a minimum of 22.2% of the platform audience for the creator must be between the ages of 18 to 25. Note that this parameter is intended to be used in conjunction with the audience_age_range parameter and will otherwise be ignored. This filter parameter is currently only supported for the YouTube and Facebook platforms. Defaults to the full range if not specified"}, "audience_locations": {"type": "array", "items": {"type": "object", "properties": {"country": {"type": "string", "description": "Specifies the country as a two-letter ISO 3166-1 alpha-2 code associated with this filter. Note that this parameter must be used in conjunction with the parameter and will otherwise be ignored. This filter parameter is currently only available for the Facebook and YouTube platforms.", "x-component": "select", "x-autocomplete": "qb/getCountries"}, "min": {"type": "number", "format": "double", "description": "Applies a minimum threshold to the parameter. Specifying a value of 20.5 when the parameter is set to \"de\", for example, means that a minimum of 20.5% of the platform audience for the creator must be located in Germany. Note that this parameter must be used in conjunction with the parameter and will otherwise be ignored. This filter parameter is currently only available for the Facebook and YouTube platforms."}}}}, "followers": {"type": "object", "description": "Applies a follower, subscriber (in the case of YouTube) or Facebook page like a range limit for the creator's platform account to use in the filter. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "views": {"type": "object", "description": "Applies a views range limit for the creator's platform account to use in the filter. This filter parameter is currently only available for the Facebook, Instagram, and YouTube platforms. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "monthly_views": {"type": "object", "description": "Applies the last month views range limit for the creator's platform account to use in the filter. This filter parameter is currently only available for all platforms except Twitch. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "v30": {"type": "object", "description": "Applies a v30 range limit for the creator's platform account to use in the filter. Refer to Tubular Video Ratings documentation for details on how v30 is calculated. This filter parameter is currently only available for the Facebook, Tiktok, Instagram, and YouTube platforms. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}}}}}}, "exclude_filter": {"type": "object", "description": "A creator filter to be excluded by the query. Defaults to exclude no videos if not specified.", "properties": {"search": {"type": "string", "description": "The search text string to be included in the filter for searching across creator names and themes. This string may include optional boolean search operators as described by the Help Center. Defaults to empty string if not specified.", "x-hint": "Use AND and OR operators", "x-placeholder": null}, "creators": {"type": "array", "x-component": "select", "x-autocomplete": "qb/searchCreators", "x-add": true, "description": "A list of one or more creator identifiers representing the creators that should be retrieved.", "items": {"type": "string"}}, "creator_types": {"type": "array", "description": "An array of creator types to use in the filter.", "x-component": "select", "x-options": {"influencer": "Influencer", "brand": "Brand", "media company": "Media Company", "aggregator": "Aggregator"}, "items": {"type": "string"}}, "creator_platforms": {"type": "array", "x-component": "select", "description": "An array of social platforms to use in the filter.", "x-options": {"youtube": "YouTube", "facebook": "Facebook", "instagram": "Instagram", "twitch": "Twitch", "tiktok": "TikTok"}, "items": {"type": "string"}}, "creator_genres": {"type": "array", "description": "An array of content genre identifiers to use in the filter. Available content genre identifiers can be obtained via a VideoFacets query. Defaults to all content genres if not specified.", "x-component": "select", "x-options": {"2": "Travel", "3": "Music & Dance", "4": "Sports", "5": "Animals & Pets", "7": "People & Blogs", "9": "Cars, Trucks & Racing", "11": "Business", "13": "Kids Entertainment & Animation", "14": "Education", "15": "Food & Drink", "16": "Fashion & Style", "19": "Health, Fitness & Self Help", "21": "Home & DIY", "22": "News & Politics", "23": "Beauty", "24": "Film & Movies", "27": "Gaming", "32": "Family & Parenting", "33": "Science & Tech", "36": "Entertainment", "37": "General Interest"}, "items": {"type": "integer"}}, "creator_countries": {"type": "array", "description": "Specifies the countries associated with the creator's accounts when limiting videos (e.g., only videos whose accounts are associated with the United States and France). Available creator countries can be obtained via a VideoFacets query. Country strings are represented as two-letter ISO 3166-1 alpha-2 codes. Defaults to all countries if not specified.", "items": {"type": "string"}, "x-component": "select", "x-autocomplete": "qb/getCountries"}, "creator_languages": {"type": "array", "description": "Specifies the dominant language of the creator to use in the filter. Languages are represented as ISO 639-1 two-letter language codes (for e.g. en, ja, es). Defaults to all languages if not specified.", "items": {"type": "string"}, "x-component": "select", "x-autocomplete": "qb/getLanguages"}, "creator_industries": {"type": "array", "description": "An array of creator industry identifiers to use in the filter. Defaults to all creator industries if not specified. Relevant for Brands.", "x-component": "select", "x-options": {"1": "Technology", "2": "Travel & Leisure", "3": "Music", "4": "CPG", "5": "Automotive", "6": "Financial & Insurance", "7": "Toys & Board Games", "8": "Media", "9": "Retail", "10": "Logistics & Heavy Industry", "11": "Other", "12": "Apparel & Accessories", "13": "Beverages", "14": "Personal Care & Health", "15": "Education", "16": "Public Service & Nonprofit", "17": "Food", "19": "Telecom", "20": "Pets", "21": "Sports Teams & Leagues", "22": "Gaming", "23": "Energy", "25": "Electronics", "27": "Broadcast, Cable, Radio, Film", "28": "Digital First Media", "29": "Magazine & Newspaper", "30": "Beauty"}, "items": {"type": "integer"}}, "creator_properties": {"type": "array", "x-component": "select", "description": "An array of creator property identifiers to use in the filter. Available creator properties can be obtained via a VideoFacets query. Defaults to all creator properties if not specified.", "x-autocomplete": "qb/searchProperties", "items": {"type": "integer"}}, "creator_list": {"type": "integer", "description": "A creator custom list identifier to use in the filter. A creator list represents a custom list of creators. These custom lists can be created and modified programmatically. See the Custom List section of the API documentation for more details. Available creator lists can be obtained via the custom_list.enumerate method. Defaults to not include a creator list.", "x-component": "select", "x-source": "qb/getCreatorLists"}, "creator_last_upload": {"type": "string", "x-component": "select", "description": "Applies a relative date filter to the number of days from the current day when a video was last uploaded by a creator. Note that the upload date is determined by the time in UTC that the video was uploaded. Defaults to all available data if not specified.", "x-options": {"last_7": "Last 7 days", "last_30": "Last 30 days", "last_90": "Last 90 days"}}, "creator_views": {"type": "object", "x-component": "integerRange", "description": "Applies a view limit (total number of views across all accounts for the previous month) to use in the filter. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "creator_rising_star": {"type": "boolean", "description": "Specifies whether to limit the filter to creators who are identified by Tubular as rising stars. If not specified, then all creators are included (i.e., both rising and non-rising stars)."}, "creator_facebook_watch": {"type": "boolean", "description": "Specifies whether to limit the filter to creators who publish a show on Facebook watch. If not specified, then all creators are included (i.e., both Facebook watch creators and non-Facebook watch creators.) Value can only be true or unspecified."}, "accounts": {"type": "array", "description": "Applies a filter limit to creators who meet the account-specific thresholds specified for a particular social platform. Defaults to all accounts if not specified.", "items": {"type": "object", "required": ["platform"], "properties": {"platform": {"type": "string", "x-component": "select", "description": "The platform name identifier associated with this account filter.", "x-options": {"youtube": "YouTube", "facebook": "Facebook", "instagram": "Instagram", "twitch": "Twitch", "tiktok": "TikTok"}}, "audience_min_male": {"type": "number", "format": "double", "description": "Applies a minimum threshold to creators whose platform audience is male. Specifying a value of 26.4, for example, means that a minimum of 26.4% of the platform audience for the creator must be male. This filter parameter is currently only available for the YouTube and Facebook platforms. Defaults to the full range if not specified."}, "audience_min_female": {"type": "number", "format": "double", "description": "Applies a minimum threshold to creators whose platform audience is female. Specifying a value of 32.1, for example, means that a minimum of 32.1% of the platform audience for the creator must be female. This filter parameter is currently only available for the YouTube and Facebook platforms. Defaults to the full range if not specified."}, "audience_age_range": {"type": "object", "description": "Applies an age range limit for the creator's platform audience to use in the filter. Note that only certain age values are currently allowed by the audience_age_range parameter. The allowable values include the following - 13, 18, 25, 35, 45, 55 Specifying either a min or max value for this parameter outside of the allowable values listed above will return an error. This filter parameter is currently only available for the YouTube and Facebook platforms. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "audience_min_age_range": {"type": "number", "format": "double", "description": "Applies a minimum threshold to the audience_age_range parameter. Specifying a value of 22.2 when audience_age_range is set to ages between 18 to 25, for example, means that a minimum of 22.2% of the platform audience for the creator must be between the ages of 18 to 25. Note that this parameter is intended to be used in conjunction with the audience_age_range parameter and will otherwise be ignored. This filter parameter is currently only supported for the YouTube and Facebook platforms. Defaults to the full range if not specified"}, "audience_locations": {"type": "array", "items": {"type": "object", "properties": {"country": {"type": "string", "description": "Specifies the country as a two-letter ISO 3166-1 alpha-2 code associated with this filter. Note that this parameter must be used in conjunction with the parameter and will otherwise be ignored. This filter parameter is currently only available for the Facebook and YouTube platforms.", "x-component": "select", "x-autocomplete": "qb/getCountries"}, "min": {"type": "number", "format": "double", "description": "Applies a minimum threshold to the parameter. Specifying a value of 20.5 when the parameter is set to \"de\", for example, means that a minimum of 20.5% of the platform audience for the creator must be located in Germany. Note that this parameter must be used in conjunction with the parameter and will otherwise be ignored. This filter parameter is currently only available for the Facebook and YouTube platforms."}}}}, "followers": {"type": "object", "description": "Applies a follower, subscriber (in the case of YouTube) or Facebook page like a range limit for the creator's platform account to use in the filter. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "views": {"type": "object", "description": "Applies a views range limit for the creator's platform account to use in the filter. This filter parameter is currently only available for the Facebook, Instagram, and YouTube platforms. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "monthly_views": {"type": "object", "description": "Applies the last month views range limit for the creator's platform account to use in the filter. This filter parameter is currently only available for all platforms except Twitch. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "v30": {"type": "object", "description": "Applies a v30 range limit for the creator's platform account to use in the filter. Refer to Tubular Video Ratings documentation for details on how v30 is calculated. This filter parameter is currently only available for the Facebook, Tiktok, Instagram, and YouTube platforms. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}}}}}}}}, "platforms": {"type": "array", "description": "A list of platforms to get monthly trends for. If not specified, data for all platforms is returned.", "x-component": "select", "items": {"type": "string"}, "x-options": {"youtube": "YouTube", "facebook": "Facebook", "instagram": "Instagram", "tiktok": "TikTok"}}, "period": {"type": "object", "description": "Months range to get metrics for. If not specified, all available months are returned.", "properties": {"since": {"type": "string", "x-component": "month", "description": "Min month in YYYY-MM format."}, "until": {"type": "string", "x-component": "month", "description": "Max month in YYYY-MM format. By default these values are set to the last full month"}}}, "sort": {"type": "object", "description": "A JSON string representation of sort-related parameters that are used to determine the order by which creator results are returned. Note that this property only needs to be specified for the initial query. This parameter will be ignored for subsequent scroll requests.", "properties": {"sort": {"type": "string", "description": "A metric to sort creators by. Defaults to \"monthly_views\" if not specified.", "x-component": "select", "x-options": {"monthly_views": {"label": "Last Month Views", "description": "Sort by views across all platforms for the previous month"}, "youtube.uploads": {"label": "YouTube uploads", "description": "Sort by total YouTube uploads"}, "youtube.views": {"label": "Total YouTube views", "description": "Sort by total YouTube views"}, "youtube.subscribers": {"label": "YouTube subscribers", "description": "Sort by total YouTube subscribers"}, "youtube.monthly_views": {"label": "YouTube monthly views", "description": "Sort by YouTube views for the previous month"}, "youtube.monthly_views_growth": {"label": "YouTube subscribers", "description": "Sort by YouTube percentage of views growth for the previous month (Monthly Views / Total Views)"}, "youtube.monthly_v30": {"label": "YouTube monthly V30", "description": "Sort by YouTube v30 for the previous month"}, "youtube.monthly_er30": {"label": "YouTube montly ER30", "description": "Sort by YouTube er30 for the previous month"}, "youtube.30d_subscribers": {"label": "YouTube 30d subscribers", "description": "Sort by YouTube 30 day subscribers"}, "youtube.30d_subscribers_growth": {"label": "YouTube 30 day subscribers growth", "description": "Sort by YouTube percentage of subscriber growth in the last 30 days (30 day Subscribers / Total Subscribers)"}, "youtube.influencer_score": {"label": "YouTube subscribers", "description": "Sort by YouTube influencer score"}, "facebook.uploads": {"label": "Facebook uploads", "description": "Sort by total Facebook uploads"}, "facebook.page_likes": {"label": "Facebook page likes", "description": "Sort by total Facebook page likes"}, "facebook.views": {"label": "Facebook views", "description": "Sort by total lifetime Facebook views"}, "facebook.monthly_views": {"label": "Facebook monthly views", "description": "Sort by Facebook views for the previous month"}, "facebook.monthly_views_growth": {"label": "Facebook monthly views growth", "description": "Sort by Facebook percentage of views growth for the previous month (Monthly Views / Total Views)"}, "facebook.monthly_v30": {"label": "Facebook V30", "description": "Sort by Facebook v30 for the previous month"}, "facebook.monthly_er30": {"label": "Facebook ER30", "description": "Sort by Facebook er30 for the previous month"}, "facebook.30d_page_likes": {"label": "Facebook 30d page likes", "description": "Sort by Facebook page_likes in the last 30 days"}, "facebook.30d_followers": {"label": "Facebook 30d followers", "description": "Sort by Facebook page_likes in the last 30 days (same as \"facebook.30d_page_likes\")"}, "facebook.30d_page_likes_growth": {"label": "Facebook 30d page likes growth", "description": "Sort by Facebook percentage of page likes growth in the last 30 days (30 day Page Likes / Total Page Likes)"}, "instagram.uploads": {"label": "Instagram uploads", "description": "Sort by total Instagram uploads"}, "instagram.followers": {"label": "Instagram followers", "description": "Sort by total Instagram followers"}, "instagram.views": {"label": "Instagram views", "description": "Sort by total lifetime Instagram views"}, "instagram.monthly_views": {"label": "Instagram monthly views", "description": "Sort by total Instagram views for the previous month"}, "instagram.monthly_views_growth": {"label": "Instagram monthly views growth", "description": "Sort by Instagram percentage of views growth for the previous month (Monthly Views / Total Views)"}, "instagram.monthly_v30": {"label": "Instagram V30", "description": "Sort by Instagram v30 for the previous month"}, "instagram.monthly_er30": {"label": "Instagram ER30", "description": "Sort by Instagram er30 for the previous month"}, "instagram.30d_followers": {"label": "Instagram 30d followers", "description": "Sort by Instagram followers in the last 30 days"}, "instagram.30d_followers_growth": {"label": "Instagram 30d followers growth", "description": "Sort by Instagram follower growth in the last 30 days (30 day Followers / Total Followers)"}, "twitch.views": {"label": "Twitch views", "description": "Sort by total lifetime Twitch views"}, "twitch.followers": {"label": "Twitch followers", "description": "Sort by total Twitch followers"}, "twitch.30d_followers": {"label": "Twitch 30d followers", "description": "Sort by Twitch followers in the last 30 days"}, "twitch.30d_followers_growth": {"label": "Twitch 30d followers growth", "description": "Sort by Twitch follower growth in the last 30 days (30 day Followers / Total Followers)"}}}, "sort_reverse": {"type": "boolean", "description": "Specifies whether to sort search results in ascending (sort_reverse=False) or descending (sort_reverse=True) order. This parameter will default to ascending (sort_reverse=False) if not specified."}}}, "scroll": {"type": "object", "description": "A JSON string representation of the scroll window to use. This should only be set after an initial query has been performed in order to page through results.", "properties": {"scroll_token": {"type": "string", "description": "A unique id associated with the current query for which results are being retrieved. Note that the scroll token will expire if not used within 1 minute."}, "scroll_size": {"type": "integer", "description": "The maximum number of results to include for each window of results. Subsequent requests to creator.search or video.search will retrieve another ScrollWindow.scroll_size results. This parameter will default to 50 if not specified. The maximum scroll window size is 200."}}}}}}}}, "responses": {"200": {"description": "Status of operation", "headers": {"Tubular-RateLimit-Overall-Limit": {"description": "The overall rate limit is 60 requests per minute. This rate limit applies to any combination of API methods that are called within a trailing 1-minute timeframe.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Overall-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Limit": {"description": "The concurrency rate limit is set to 1. This means that no more than a single request can be made at a time (i.e., in parallel). Attempting to issue a video.search request while a video.facets request is still running, for example will cause the video.search request to return a rate_limited error.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Remaining": {"description": "Number of concurrent requests available for use.", "schema": {"type": "integer"}}, "Tubular-Quota-Rows-Consumed": {"description": "Number of rows consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Consumed": {"description": "Number of quota units consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Limit": {"description": "Total quota units available for the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Remaining": {"description": "Number of quota units remaining in the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Expires-After": {"description": "Date and time when the current quota period ends.", "schema": {"type": "string", "format": "date-time"}}}, "content": {"application/json": {"schema": {"type": "object", "properties": {"ok": {"type": "boolean", "description": "Whether request was successful."}, "total": {"type": "integer", "description": "Total number of creators matching the query."}, "scroll_id": {"type": "string", "description": "Unique identifier to get the next page of results."}, "trends": {"type": "array", "description": "A list of creators' monthly trends", "items": {"type": "object", "properties": {"id": {"type": "string", "description": "Creator ID the row pertains to."}, "trends": {"type": "array", "items": {"type": "object", "properties": {"platform": {"type": "string", "description": "A platform the metrics are returned for."}, "month": {"type": "string", "description": "A month the metric are provided for."}, "views": {"type": "integer", "description": "The number of views gained within the month."}, "views_growth": {"type": "number", "format": "double", "description": "Views growth over the given month compared to the total views on the beginning of the month."}, "views_growth_yoy": {"type": "number", "format": "double", "description": "All-time views growth over the year until the given month."}, "views_growth_mom": {"type": "number", "format": "double", "description": "Views growth compared to a previous month."}, "views_all_time": {"type": "integer", "description": "Total views by the end of the month."}, "engagements": {"type": "integer", "description": "The number of engagements gained within the month."}, "engagements_growth": {"type": "number", "format": "double", "description": "Engagements growth over the given month compared to the total engagements on the beginning of the month."}, "engagements_growth_yoy": {"type": "number", "format": "double", "description": "All-time engagements growth over the year until the given month."}, "engagements_growth_mom": {"type": "number", "format": "double", "description": "Engagements growth compared to a previous month."}, "engagements_all_time": {"type": "integer", "description": "Total engagements by the end of the month."}, "followers": {"type": "integer", "description": "The number of followers gained within the month."}, "followers_growth": {"type": "number", "format": "double", "description": "All-time followers growth over the year until the given month."}, "followers_growth_yoy": {"type": "number", "format": "double", "description": "Followers growth over the year since the given month compared to the total followers a creator had a year prior to the given month."}, "followers_growth_mom": {"type": "number", "format": "double", "description": "Followers growth compared to a previous month."}, "followers_all_time": {"type": "integer", "description": "Total followers by the end of the month."}, "er": {"type": "number", "format": "double", "description": "Average engagement rating across videos."}, "v30": {"type": "number", "format": "double", "description": "Average views videos get 30 days after uploading."}, "e30": {"type": "number", "format": "double", "description": "Average engagements videos get 30 days after uploading."}}}}}}}}}}}}, "429": {"description": "The query is rate-limited.", "headers": {"Tubular-RateLimit-Overall-Limit": {"description": "The overall rate limit is 60 requests per minute. This rate limit applies to any combination of API methods that are called within a trailing 1-minute timeframe.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Overall-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Limit": {"description": "The concurrency rate limit is set to 1. This means that no more than a single request can be made at a time (i.e., in parallel). Attempting to issue a video.search request while a video.facets request is still running, for example will cause the video.search request to return a rate_limited error.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Remaining": {"description": "Number of concurrent requests available for use.", "schema": {"type": "integer"}}, "Tubular-Quota-Rows-Consumed": {"description": "Number of rows consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Consumed": {"description": "Number of quota units consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Limit": {"description": "Total quota units available for the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Remaining": {"description": "Number of quota units remaining in the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Expires-After": {"description": "Date and time when the current quota period ends.", "schema": {"type": "string", "format": "date-time"}}}}}}}, "/creator.details": {"x-requires": ["api_intelligence"], "x-group": ["data", "creator"], "post": {"summary": "Get creator details for one or more creator IDs.", "parameters": [{"in": "header", "description": "Tubular API key.", "name": "Api-Key", "schema": {"type": "string"}}], "requestBody": {"content": {"application/json": {"schema": {"type": "object", "required": ["creator_ids"], "properties": {"creator_ids": {"type": "array", "x-component": "select", "x-autocomplete": "qb/searchCreators", "x-add": true, "description": "A list of one or more creator identifiers representing the creators that should be retrieved.", "items": {"type": "string"}}}}}}}, "responses": {"200": {"description": "Status of operation", "headers": {"Tubular-RateLimit-Overall-Limit": {"description": "The overall rate limit is 60 requests per minute. This rate limit applies to any combination of API methods that are called within a trailing 1-minute timeframe.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Overall-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Limit": {"description": "The concurrency rate limit is set to 1. This means that no more than a single request can be made at a time (i.e., in parallel). Attempting to issue a video.search request while a video.facets request is still running, for example will cause the video.search request to return a rate_limited error.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Remaining": {"description": "Number of concurrent requests available for use.", "schema": {"type": "integer"}}, "Tubular-Quota-Rows-Consumed": {"description": "Number of rows consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Consumed": {"description": "Number of quota units consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Limit": {"description": "Total quota units available for the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Remaining": {"description": "Number of quota units remaining in the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Expires-After": {"description": "Date and time when the current quota period ends.", "schema": {"type": "string", "format": "date-time"}}, "Tubular-RateLimit-UniqueCreatorLimit-Limit": {"description": "Defines the total number of unique creators a client can retrieve in the current month.", "schema": {"type": "integer"}}, "Tubular-RateLimit-UniqueCreatorLimit-Remaining": {"description": "A number of unique creators left in this month.", "schema": {"type": "integer"}}, "Tubular-RateLimit-UniqueCreatorLimit-ExpiresAfter": {"description": "Specifies the date when the quota resets. Usually a beginning of each month.", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"type": "object", "properties": {"ok": {"type": "boolean", "description": "Standard API response for success/failure."}, "creators": {"type": "array", "description": "A list of JSON objects representing creator information for the requested creator IDs. The creators will be provided in the same order that was specified by the creator_ids parameter in the request.", "items": {"type": "object", "properties": {"creator_id": {"type": "string", "description": "Creator identifier for a particular creator. A creator id is guaranteed to be globally unique (i.e., no two creators will ever use the same id). You can use a creator.details query to gather more information about a specific creator."}, "title": {"type": "string", "description": "The title of the creator."}, "description": {"type": "string", "description": "The description of the creator."}, "thumbnail_url": {"type": "string", "description": "The URL of the thumbnail image for this creator."}, "type": {"type": "string", "description": "The type of creator."}, "country": {"type": "string", "description": "The two-letter ISO 3166-1 alpha-2 country code associated with the creator."}, "language": {"type": "string", "description": "The ISO 639-1 two-letter language code associated with the dominant language of the creator."}, "genre": {"type": "object", "description": "The content category associated with the creator", "properties": {"id": {"type": "integer", "description": "The identifier associated with a content category."}, "title": {"type": "string", "description": "The title associated with a content category."}}}, "industry": {"type": "object", "description": "The industry associated with the creator.", "properties": {"id": {"type": "integer", "description": "The unique identifier associated with the current industry."}, "title": {"type": "string", "description": "The title of the current industry."}}}, "properties": {"type": "array", "description": "An array of JSON objects representing the parent properties associated with this creator. Note that a single creator can have a series of parent properties associated with it, which Tubular stores as a hierarchical parent-child relationship. This property parameter represents all ancestors of a like the range parent hierarchy.", "items": {"type": "object", "properties": {"id": {"type": "integer", "description": "The unique identifier associated with the current property."}, "title": {"type": "string", "description": "The title of the current property."}}}}, "direct_property": {"type": "object", "description": "Direct property a creator is assiciated with.", "properties": {"id": {"type": "integer", "description": "The unique identifier associated with the property."}, "title": {"type": "string", "description": "The title of the property."}}}, "views": {"type": "integer", "description": "Total views across all accounts for the creator."}, "uploads_90d": {"type": "integer", "description": "A total number of video uploads by this creator within the last 90 days."}, "last_upload_date": {"type": "string", "description": "The date a video was last uploaded by the creator in \"YYYY-MM-DD\" format. Note that the upload date is determined by the time in UTC that the video was uploaded."}, "accounts": {"type": "array", "description": "A list of JSON string objects representing the social accounts for the current creator. Each object represents an account from a different social platform.", "items": {"type": "object", "properties": {"platform": {"type": "string", "description": "The social platform associated with an account."}, "title": {"type": "string", "description": "The title of the account."}, "description": {"type": "string", "description": "The description associated with an account."}, "account_url": {"type": "string", "description": "The URL for an account."}, "thumbnail_url": {"type": "string", "description": "The URL of the thumbnail image for an account."}, "views": {"type": "integer", "description": "Total views over time for an account."}, "followers": {"type": "integer", "description": "Total subscribers for a YouTube account, page likes for Facebook or total followers for all other platforms."}, "monthly_stats": {"type": "object", "description": "Monthly stats for an account.", "properties": {"views": {"type": "object", "description": "Historical monthly views.", "properties": {"month": {"type": "string", "description": "A calendar month value is attributed to."}, "value": {"type": "integer", "description": "The metric value for the given month."}}}}}, "monthly_views": {"type": "integer", "description": "Total views for an account for the previous month."}, "monthly_demographic_views": {"type": "array", "description": "Demographic stats for the latest month if was requested (see \"Creator Search\" section). It shows summarized views for requested set of locations calculated only for the last full month.", "items": {"type": "object", "properties": {"countries": {"type": "array", "description": "list of country codes (ISO 3166-1 alpha-2 country code)", "items": {"type": "string"}}, "views": {"type": "integer", "description": "Total amount of views calculated for the specified countries for the last month Currently this data can be returned only for YouTube accounts"}}}}, "monthly_views_growth": {"type": "number", "format": "double", "description": "Percentage of views growth for the previous month (Monthly Views / Total Views)"}, "monthly_v30": {"type": "integer", "description": "The v30 across all videos for an account for the previous month. Refer to Tubular Video Ratings documentation for details on how v30 is calculated."}, "monthly_er30": {"type": "integer", "description": "The er30 across all videos for an account for the previous month. Refer to Tubular Video Ratings documentation for details on how v30 is calculated."}, "30d_followers": {"type": "integer", "description": "A number of YouTube subscribers, Facebook page likes or followers for all other platforms that have been gained within the last 30 days. This parameter is available for Facebook, TikTok, Instagram, and YouTube platforms. A null value will be returned for all other platforms."}, "30d_followers_growth": {"type": "number", "format": "double", "description": "Percentage of overall subscribers/page likes/followers that have grown within the last 30 days. This parameter is available for Facebook, TikTok, Instagram, and YouTube platforms. A null value will be returned for all other platforms."}, "influencer_score": {"type": "number", "format": "double", "description": "An account's influencer score. More information about how influencer scores are calculated can be found in Tubular's Help Center documentation. This parameter is currently only available for the YouTube platform. A null value will be returned for all other platforms."}, "category": {"type": "object", "description": "The content category associated with an account.", "properties": {"id": {"type": "integer", "description": "The identifier associated with a content category."}, "title": {"type": "string", "description": "The title associated with a content category."}}}, "audience_ages": {"type": "array", "description": "An array of JSON objects representing audience age ranges for a particular account. This is currently only available for the YouTube platform.", "items": {"type": "object", "properties": {"range": {"type": "string", "description": "A particular age range represented by a string formatted as \"ages_X_Y\", where X is the minimum value in the range and Y is the maximum value in the range. A minimum value of 18 and a maximum value of 24 represents an age range between the age of 18 to 24."}, "value": {"type": "number", "format": "double", "description": "The percentage value assigned to the associated age range. A value of 22.2, for example, means that 22.2% of the platform audience was associated with the current audience_ages.range age range."}}}}, "audience_locations": {"type": "array", "description": "An array of JSON objects representing the audience locations for a particular account. This is currently only available for the YouTube and Facebook platforms.", "items": {"type": "object", "properties": {"country": {"type": "string", "description": "The two-letter ISO 3166-1 alpha-2 country code associated with the current location."}, "value": {"type": "number", "format": "double", "description": "The percentage value assigned to the associated country. A value of 32.2, for example, means that 32.2% of the platform audience was associated with the current audience_locations.country location."}}}}, "audience_genders": {"type": "array", "description": "An array of JSON objects representing the audience genders for a particular account.", "items": {"type": "object", "properties": {"gender": {"type": "string", "description": "Gender type, possible values \"male\", \"female\""}, "value": {"type": "number", "format": "double", "description": "Percentage in the audience of the specified gender type"}}}}, "audience_last_updated": {"type": "string", "description": "The date that audience data was last updated."}}}}}}}, "sort": {"type": "object", "description": "A JSON string representation of sort-related parameters that are used to determine the order by which creator results are returned. Note that this property only needs to be specified for the initial query. This parameter will be ignored for subsequent scroll requests.", "properties": {"sort": {"type": "string", "description": "A metric to sort creators by. Defaults to \"monthly_views\" if not specified.", "x-options": {"monthly_views": {"label": "Monthly Views", "description": "Sort by views across all platforms for the previous month"}, "youtube.uploads": {"label": "YouTube uploads", "description": "Sort by total YouTube uploads"}, "youtube.views": {"label": "YouTube views", "description": "Sort by total YouTube views"}, "youtube.subscribers": {"label": "YouTube subscribers", "description": "Sort by total YouTube subscribers"}, "youtube.monthly_views": {"label": "YouTube subscribers", "description": "Sort by YouTube views for the previous month"}, "youtube.monthly_views_growth": {"label": "YouTube subscribers", "description": "Sort by YouTube percentage of views growth for the previous month (Monthly Views / Total Views)"}, "youtube.monthly_v30": {"label": "YouTube monthly V30", "description": "Sort by YouTube v30 for the previous month"}, "youtube.monthly_er30": {"label": "YouTube montly ER30", "description": "Sort by YouTube er30 for the previous month"}, "youtube.30d_subscribers": {"label": "YouTube 30d subscribers", "description": "Sort by YouTube 30 day subscribers"}, "youtube.30d_subscribers_growth": {"label": "YouTube 30 day subscribers growth", "description": "Sort by YouTube percentage of subscriber growth in the last 30 days (30 day Subscribers / Total Subscribers)"}, "youtube.influencer_score": {"label": "YouTube subscribers", "description": "Sort by YouTube influencer score"}, "facebook.uploads": {"label": "Facebook uploads", "description": "Sort by total Facebook uploads"}, "facebook.page_likes": {"label": "Facebook page likes", "description": "Sort by total Facebook page likes"}, "facebook.views": {"label": "Facebook views", "description": "Sort by total lifetime Facebook views"}, "facebook.monthly_views": {"label": "Facebook monthly views", "description": "Sort by Facebook views for the previous month"}, "facebook.monthly_views_growth": {"label": "Facebook monthly views growth", "description": "Sort by Facebook percentage of views growth for the previous month (Monthly Views / Total Views)"}, "facebook.monthly_v30": {"label": "Facebook V30", "description": "Sort by Facebook v30 for the previous month"}, "facebook.monthly_er30": {"label": "Facebook ER30", "description": "Sort by Facebook er30 for the previous month"}, "facebook.30d_page_likes": {"label": "Facebook 30d page likes", "description": "Sort by Facebook page_likes in the last 30 days"}, "facebook.30d_followers": {"label": "Facebook 30d followers", "description": "Sort by Facebook page_likes in the last 30 days (same as \"facebook.30d_page_likes\")"}, "facebook.30d_page_likes_growth": {"label": "Facebook 30d page likes growth", "description": "Sort by Facebook percentage of page likes growth in the last 30 days (30 day Page Likes / Total Page Likes)"}, "instagram.uploads": {"label": "Instagram uploads", "description": "Sort by total Instagram uploads"}, "instagram.followers": {"label": "Instagram followers", "description": "Sort by total Instagram followers"}, "instagram.views": {"label": "Instagram views", "description": "Sort by total lifetime Instagram views"}, "instagram.monthly_views": {"label": "Instagram monthly views", "description": "Sort by total Instagram views for the previous month"}, "instagram.monthly_views_growth": {"label": "Instagram monthly views growth", "description": "Sort by Instagram percentage of views growth for the previous month (Monthly Views / Total Views)"}, "instagram.monthly_v30": {"label": "Instagram V30", "description": "Sort by Instagram v30 for the previous month"}, "instagram.monthly_er30": {"label": "Instagram ER30", "description": "Sort by Instagram er30 for the previous month"}, "instagram.30d_followers": {"label": "Instagram 30d followers", "description": "Sort by Instagram followers in the last 30 days"}, "instagram.30d_followers_growth": {"label": "Instagram 30d followers growth", "description": "Sort by Instagram follower growth in the last 30 days (30 day Followers / Total Followers)"}, "twitch.views": {"label": "Twitch views", "description": "Sort by total lifetime Twitch views"}, "twitch.followers": {"label": "Twitch followers", "description": "Sort by total Twitch followers"}, "twitch.30d_followers": {"label": "Twitch 30d followers", "description": "Sort by Twitch followers in the last 30 days"}, "twitch.30d_followers_growth": {"label": "Twitch 30d followers growth", "description": "Sort by Twitch follower growth in the last 30 days (30 day Followers / Total Followers)"}}}}}}}}}}, "429": {"description": "The query is rate-limited.", "headers": {"Tubular-RateLimit-Overall-Limit": {"description": "The overall rate limit is 60 requests per minute. This rate limit applies to any combination of API methods that are called within a trailing 1-minute timeframe.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Overall-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Limit": {"description": "The concurrency rate limit is set to 1. This means that no more than a single request can be made at a time (i.e., in parallel). Attempting to issue a video.search request while a video.facets request is still running, for example will cause the video.search request to return a rate_limited error.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Remaining": {"description": "Number of concurrent requests available for use.", "schema": {"type": "integer"}}, "Tubular-Quota-Rows-Consumed": {"description": "Number of rows consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Consumed": {"description": "Number of quota units consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Limit": {"description": "Total quota units available for the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Remaining": {"description": "Number of quota units remaining in the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Expires-After": {"description": "Date and time when the current quota period ends.", "schema": {"type": "string", "format": "date-time"}}, "Tubular-RateLimit-UniqueCreatorLimit-Limit": {"description": "Defines the total number of unique creators a client can retrieve in the current month.", "schema": {"type": "integer"}}, "Tubular-RateLimit-UniqueCreatorLimit-Remaining": {"description": "A number of unique creators left in this month.", "schema": {"type": "integer"}}, "Tubular-RateLimit-UniqueCreatorLimit-ExpiresAfter": {"description": "Specifies the date when the quota resets. Usually a beginning of each month.", "schema": {"type": "integer"}}}}}}}, "/creator.trends": {"x-requires": ["api_intelligence"], "x-group": ["data", "creator"], "post": {"summary": "Get per-platform historical daily metrics for a a particular creator.", "parameters": [{"in": "header", "description": "Tubular API key.", "name": "Api-Key", "schema": {"type": "string"}}], "requestBody": {"content": {"application/json": {"schema": {"type": "object", "required": ["creator_id", "metrics", "date_range"], "properties": {"creator_id": {"type": "string", "x-component": "select", "x-add": true, "x-autocomplete": "qb/searchCreators", "description": "A creator identifier representing the creator that trends should be retrieved for."}, "metrics": {"type": "array", "x-component": "select", "items": {"type": "string"}, "x-options": {"views": "Views", "engagements": "Engagements", "uploads": "Uploads", "followers": "Followers"}}, "date_range": {"type": "object", "x-component": "dateRange", "description": "Defines a date range to get trends data for.", "properties": {"min": {"type": "string", "description": "The minimum date to be included as part of a range of dates in \"YYYY-MM-DD\"", "x-component": "date"}, "max": {"type": "string", "description": "The maximum date to be included as part of a range of dates in \"YYYY-MM-DD\" format.", "x-component": "date"}}, "x-options": [{"label": "Last day", "value": "last_day"}, {"label": "Last week", "value": "last_7"}, {"label": "Last 30 days", "value": "last_30"}, {"label": "Last 90 days", "value": "last_90"}, {"label": "Last year", "value": "last_1_y"}, {"label": "Last two years", "value": "last_2_y"}, {"label": "Last three years", "value": "last_3_y"}, {"label": "All time", "value": "all_time"}, {"label": "Custom Date Range", "value": {"handler": "custom"}}]}}}}}}, "responses": {"200": {"description": "Status of operation", "headers": {"Tubular-RateLimit-Overall-Limit": {"description": "The overall rate limit is 60 requests per minute. This rate limit applies to any combination of API methods that are called within a trailing 1-minute timeframe.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Overall-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Limit": {"description": "The concurrency rate limit is set to 1. This means that no more than a single request can be made at a time (i.e., in parallel). Attempting to issue a video.search request while a video.facets request is still running, for example will cause the video.search request to return a rate_limited error.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Remaining": {"description": "Number of concurrent requests available for use.", "schema": {"type": "integer"}}, "Tubular-Quota-Rows-Consumed": {"description": "Number of rows consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Consumed": {"description": "Number of quota units consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Limit": {"description": "Total quota units available for the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Remaining": {"description": "Number of quota units remaining in the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Expires-After": {"description": "Date and time when the current quota period ends.", "schema": {"type": "string", "format": "date-time"}}}, "content": {"application/json": {"schema": {"type": "object", "properties": {"ok": {"type": "boolean", "description": "Standard API response for success/failure."}, "platform_trends": {"type": "array", "description": "A list of platform-specific trends associated with the requested creator.", "items": {"type": "object", "properties": {"platform": {"type": "string", "description": "The platform associated with the current trends."}, "trends": {"type": "array", "description": "A list of metric-specific trends associated with the current platform and requested creator.", "items": {"type": "object", "properties": {"metric": {"type": "string", "description": "The metric associated with the current trends."}, "dates": {"type": "array", "description": "A list of date strings corresponding to metric values over time.", "items": {"type": "string"}}, "values": {"type": "array", "description": "A list of values accumulated over a particular day for the corresponding metric. For example, a value of 400 for the views metric for a particular date means that the video acquired 400 views on that day.", "items": {"type": "integer"}}}}}}}}}}}}}, "429": {"description": "The query is rate-limited.", "headers": {"Tubular-RateLimit-Overall-Limit": {"description": "The overall rate limit is 60 requests per minute. This rate limit applies to any combination of API methods that are called within a trailing 1-minute timeframe.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Overall-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Limit": {"description": "The concurrency rate limit is set to 1. This means that no more than a single request can be made at a time (i.e., in parallel). Attempting to issue a video.search request while a video.facets request is still running, for example will cause the video.search request to return a rate_limited error.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Remaining": {"description": "Number of concurrent requests available for use.", "schema": {"type": "integer"}}, "Tubular-Quota-Rows-Consumed": {"description": "Number of rows consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Consumed": {"description": "Number of quota units consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Limit": {"description": "Total quota units available for the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Remaining": {"description": "Number of quota units remaining in the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Expires-After": {"description": "Date and time when the current quota period ends.", "schema": {"type": "string", "format": "date-time"}}}}}}}, "/creator.summary": {"x-requires": ["api_intelligence"], "x-group": ["data", "creator"], "post": {"summary": "Get a by-platform breakdown of summary statistics pertaining to a particular creator search query.", "parameters": [{"in": "header", "description": "Tubular API key.", "name": "Api-Key", "schema": {"type": "string"}}], "requestBody": {"content": {"application/json": {"schema": {"type": "object", "required": ["query"], "properties": {"query": {"type": "object", "description": "Defines search criteria that combines include and exclude filters.", "properties": {"savedsearch_id": {"type": "integer", "x-component": "select", "description": "Creator saved search id", "x-source": "qb/getCreatorSavedSearches"}, "include_filter": {"type": "object", "description": "A creator filter to be included by the query. Defaults to include everything if not specified.", "properties": {"search": {"type": "string", "description": "The search text string to be included in the filter for searching across creator names and themes. This string may include optional boolean search operators as described by the Help Center. Defaults to empty string if not specified.", "x-hint": "Use AND and OR operators", "x-placeholder": null}, "creators": {"type": "array", "x-component": "select", "x-autocomplete": "qb/searchCreators", "x-add": true, "description": "A list of one or more creator identifiers representing the creators that should be retrieved.", "items": {"type": "string"}}, "creator_types": {"type": "array", "description": "An array of creator types to use in the filter.", "x-component": "select", "x-options": {"influencer": "Influencer", "brand": "Brand", "media company": "Media Company", "aggregator": "Aggregator"}, "items": {"type": "string"}}, "creator_platforms": {"type": "array", "x-component": "select", "description": "An array of social platforms to use in the filter.", "x-options": {"youtube": "YouTube", "facebook": "Facebook", "instagram": "Instagram", "twitch": "Twitch", "tiktok": "TikTok"}, "items": {"type": "string"}}, "creator_genres": {"type": "array", "description": "An array of content genre identifiers to use in the filter. Available content genre identifiers can be obtained via a VideoFacets query. Defaults to all content genres if not specified.", "x-component": "select", "x-options": {"2": "Travel", "3": "Music & Dance", "4": "Sports", "5": "Animals & Pets", "7": "People & Blogs", "9": "Cars, Trucks & Racing", "11": "Business", "13": "Kids Entertainment & Animation", "14": "Education", "15": "Food & Drink", "16": "Fashion & Style", "19": "Health, Fitness & Self Help", "21": "Home & DIY", "22": "News & Politics", "23": "Beauty", "24": "Film & Movies", "27": "Gaming", "32": "Family & Parenting", "33": "Science & Tech", "36": "Entertainment", "37": "General Interest"}, "items": {"type": "integer"}}, "creator_countries": {"type": "array", "description": "Specifies the countries associated with the creator's accounts when limiting videos (e.g., only videos whose accounts are associated with the United States and France). Available creator countries can be obtained via a VideoFacets query. Country strings are represented as two-letter ISO 3166-1 alpha-2 codes. Defaults to all countries if not specified.", "items": {"type": "string"}, "x-component": "select", "x-autocomplete": "qb/getCountries"}, "creator_languages": {"type": "array", "description": "Specifies the dominant language of the creator to use in the filter. Languages are represented as ISO 639-1 two-letter language codes (for e.g. en, ja, es). Defaults to all languages if not specified.", "items": {"type": "string"}, "x-component": "select", "x-autocomplete": "qb/getLanguages"}, "creator_industries": {"type": "array", "description": "An array of creator industry identifiers to use in the filter. Defaults to all creator industries if not specified. Relevant for Brands.", "x-component": "select", "x-options": {"1": "Technology", "2": "Travel & Leisure", "3": "Music", "4": "CPG", "5": "Automotive", "6": "Financial & Insurance", "7": "Toys & Board Games", "8": "Media", "9": "Retail", "10": "Logistics & Heavy Industry", "11": "Other", "12": "Apparel & Accessories", "13": "Beverages", "14": "Personal Care & Health", "15": "Education", "16": "Public Service & Nonprofit", "17": "Food", "19": "Telecom", "20": "Pets", "21": "Sports Teams & Leagues", "22": "Gaming", "23": "Energy", "25": "Electronics", "27": "Broadcast, Cable, Radio, Film", "28": "Digital First Media", "29": "Magazine & Newspaper", "30": "Beauty"}, "items": {"type": "integer"}}, "creator_properties": {"type": "array", "x-component": "select", "description": "An array of creator property identifiers to use in the filter. Available creator properties can be obtained via a VideoFacets query. Defaults to all creator properties if not specified.", "x-autocomplete": "qb/searchProperties", "items": {"type": "integer"}}, "creator_list": {"type": "integer", "description": "A creator custom list identifier to use in the filter. A creator list represents a custom list of creators. These custom lists can be created and modified programmatically. See the Custom List section of the API documentation for more details. Available creator lists can be obtained via the custom_list.enumerate method. Defaults to not include a creator list.", "x-component": "select", "x-source": "qb/getCreatorLists"}, "creator_last_upload": {"type": "string", "x-component": "select", "description": "Applies a relative date filter to the number of days from the current day when a video was last uploaded by a creator. Note that the upload date is determined by the time in UTC that the video was uploaded. Defaults to all available data if not specified.", "x-options": {"last_7": "Last 7 days", "last_30": "Last 30 days", "last_90": "Last 90 days"}}, "creator_views": {"type": "object", "x-component": "integerRange", "description": "Applies a view limit (total number of views across all accounts for the previous month) to use in the filter. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "creator_rising_star": {"type": "boolean", "description": "Specifies whether to limit the filter to creators who are identified by Tubular as rising stars. If not specified, then all creators are included (i.e., both rising and non-rising stars)."}, "creator_facebook_watch": {"type": "boolean", "description": "Specifies whether to limit the filter to creators who publish a show on Facebook watch. If not specified, then all creators are included (i.e., both Facebook watch creators and non-Facebook watch creators.) Value can only be true or unspecified."}, "accounts": {"type": "array", "description": "Applies a filter limit to creators who meet the account-specific thresholds specified for a particular social platform. Defaults to all accounts if not specified.", "items": {"type": "object", "required": ["platform"], "properties": {"platform": {"type": "string", "x-component": "select", "description": "The platform name identifier associated with this account filter.", "x-options": {"youtube": "YouTube", "facebook": "Facebook", "instagram": "Instagram", "twitch": "Twitch", "tiktok": "TikTok"}}, "audience_min_male": {"type": "number", "format": "double", "description": "Applies a minimum threshold to creators whose platform audience is male. Specifying a value of 26.4, for example, means that a minimum of 26.4% of the platform audience for the creator must be male. This filter parameter is currently only available for the YouTube and Facebook platforms. Defaults to the full range if not specified."}, "audience_min_female": {"type": "number", "format": "double", "description": "Applies a minimum threshold to creators whose platform audience is female. Specifying a value of 32.1, for example, means that a minimum of 32.1% of the platform audience for the creator must be female. This filter parameter is currently only available for the YouTube and Facebook platforms. Defaults to the full range if not specified."}, "audience_age_range": {"type": "object", "description": "Applies an age range limit for the creator's platform audience to use in the filter. Note that only certain age values are currently allowed by the audience_age_range parameter. The allowable values include the following - 13, 18, 25, 35, 45, 55 Specifying either a min or max value for this parameter outside of the allowable values listed above will return an error. This filter parameter is currently only available for the YouTube and Facebook platforms. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "audience_min_age_range": {"type": "number", "format": "double", "description": "Applies a minimum threshold to the audience_age_range parameter. Specifying a value of 22.2 when audience_age_range is set to ages between 18 to 25, for example, means that a minimum of 22.2% of the platform audience for the creator must be between the ages of 18 to 25. Note that this parameter is intended to be used in conjunction with the audience_age_range parameter and will otherwise be ignored. This filter parameter is currently only supported for the YouTube and Facebook platforms. Defaults to the full range if not specified"}, "audience_locations": {"type": "array", "items": {"type": "object", "properties": {"country": {"type": "string", "description": "Specifies the country as a two-letter ISO 3166-1 alpha-2 code associated with this filter. Note that this parameter must be used in conjunction with the parameter and will otherwise be ignored. This filter parameter is currently only available for the Facebook and YouTube platforms.", "x-component": "select", "x-autocomplete": "qb/getCountries"}, "min": {"type": "number", "format": "double", "description": "Applies a minimum threshold to the parameter. Specifying a value of 20.5 when the parameter is set to \"de\", for example, means that a minimum of 20.5% of the platform audience for the creator must be located in Germany. Note that this parameter must be used in conjunction with the parameter and will otherwise be ignored. This filter parameter is currently only available for the Facebook and YouTube platforms."}}}}, "followers": {"type": "object", "description": "Applies a follower, subscriber (in the case of YouTube) or Facebook page like a range limit for the creator's platform account to use in the filter. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "views": {"type": "object", "description": "Applies a views range limit for the creator's platform account to use in the filter. This filter parameter is currently only available for the Facebook, Instagram, and YouTube platforms. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "monthly_views": {"type": "object", "description": "Applies the last month views range limit for the creator's platform account to use in the filter. This filter parameter is currently only available for all platforms except Twitch. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "v30": {"type": "object", "description": "Applies a v30 range limit for the creator's platform account to use in the filter. Refer to Tubular Video Ratings documentation for details on how v30 is calculated. This filter parameter is currently only available for the Facebook, Tiktok, Instagram, and YouTube platforms. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}}}}}}, "exclude_filter": {"type": "object", "description": "A creator filter to be excluded by the query. Defaults to exclude no videos if not specified.", "properties": {"search": {"type": "string", "description": "The search text string to be included in the filter for searching across creator names and themes. This string may include optional boolean search operators as described by the Help Center. Defaults to empty string if not specified.", "x-hint": "Use AND and OR operators", "x-placeholder": null}, "creators": {"type": "array", "x-component": "select", "x-autocomplete": "qb/searchCreators", "x-add": true, "description": "A list of one or more creator identifiers representing the creators that should be retrieved.", "items": {"type": "string"}}, "creator_types": {"type": "array", "description": "An array of creator types to use in the filter.", "x-component": "select", "x-options": {"influencer": "Influencer", "brand": "Brand", "media company": "Media Company", "aggregator": "Aggregator"}, "items": {"type": "string"}}, "creator_platforms": {"type": "array", "x-component": "select", "description": "An array of social platforms to use in the filter.", "x-options": {"youtube": "YouTube", "facebook": "Facebook", "instagram": "Instagram", "twitch": "Twitch", "tiktok": "TikTok"}, "items": {"type": "string"}}, "creator_genres": {"type": "array", "description": "An array of content genre identifiers to use in the filter. Available content genre identifiers can be obtained via a VideoFacets query. Defaults to all content genres if not specified.", "x-component": "select", "x-options": {"2": "Travel", "3": "Music & Dance", "4": "Sports", "5": "Animals & Pets", "7": "People & Blogs", "9": "Cars, Trucks & Racing", "11": "Business", "13": "Kids Entertainment & Animation", "14": "Education", "15": "Food & Drink", "16": "Fashion & Style", "19": "Health, Fitness & Self Help", "21": "Home & DIY", "22": "News & Politics", "23": "Beauty", "24": "Film & Movies", "27": "Gaming", "32": "Family & Parenting", "33": "Science & Tech", "36": "Entertainment", "37": "General Interest"}, "items": {"type": "integer"}}, "creator_countries": {"type": "array", "description": "Specifies the countries associated with the creator's accounts when limiting videos (e.g., only videos whose accounts are associated with the United States and France). Available creator countries can be obtained via a VideoFacets query. Country strings are represented as two-letter ISO 3166-1 alpha-2 codes. Defaults to all countries if not specified.", "items": {"type": "string"}, "x-component": "select", "x-autocomplete": "qb/getCountries"}, "creator_languages": {"type": "array", "description": "Specifies the dominant language of the creator to use in the filter. Languages are represented as ISO 639-1 two-letter language codes (for e.g. en, ja, es). Defaults to all languages if not specified.", "items": {"type": "string"}, "x-component": "select", "x-autocomplete": "qb/getLanguages"}, "creator_industries": {"type": "array", "description": "An array of creator industry identifiers to use in the filter. Defaults to all creator industries if not specified. Relevant for Brands.", "x-component": "select", "x-options": {"1": "Technology", "2": "Travel & Leisure", "3": "Music", "4": "CPG", "5": "Automotive", "6": "Financial & Insurance", "7": "Toys & Board Games", "8": "Media", "9": "Retail", "10": "Logistics & Heavy Industry", "11": "Other", "12": "Apparel & Accessories", "13": "Beverages", "14": "Personal Care & Health", "15": "Education", "16": "Public Service & Nonprofit", "17": "Food", "19": "Telecom", "20": "Pets", "21": "Sports Teams & Leagues", "22": "Gaming", "23": "Energy", "25": "Electronics", "27": "Broadcast, Cable, Radio, Film", "28": "Digital First Media", "29": "Magazine & Newspaper", "30": "Beauty"}, "items": {"type": "integer"}}, "creator_properties": {"type": "array", "x-component": "select", "description": "An array of creator property identifiers to use in the filter. Available creator properties can be obtained via a VideoFacets query. Defaults to all creator properties if not specified.", "x-autocomplete": "qb/searchProperties", "items": {"type": "integer"}}, "creator_list": {"type": "integer", "description": "A creator custom list identifier to use in the filter. A creator list represents a custom list of creators. These custom lists can be created and modified programmatically. See the Custom List section of the API documentation for more details. Available creator lists can be obtained via the custom_list.enumerate method. Defaults to not include a creator list.", "x-component": "select", "x-source": "qb/getCreatorLists"}, "creator_last_upload": {"type": "string", "x-component": "select", "description": "Applies a relative date filter to the number of days from the current day when a video was last uploaded by a creator. Note that the upload date is determined by the time in UTC that the video was uploaded. Defaults to all available data if not specified.", "x-options": {"last_7": "Last 7 days", "last_30": "Last 30 days", "last_90": "Last 90 days"}}, "creator_views": {"type": "object", "x-component": "integerRange", "description": "Applies a view limit (total number of views across all accounts for the previous month) to use in the filter. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "creator_rising_star": {"type": "boolean", "description": "Specifies whether to limit the filter to creators who are identified by Tubular as rising stars. If not specified, then all creators are included (i.e., both rising and non-rising stars)."}, "creator_facebook_watch": {"type": "boolean", "description": "Specifies whether to limit the filter to creators who publish a show on Facebook watch. If not specified, then all creators are included (i.e., both Facebook watch creators and non-Facebook watch creators.) Value can only be true or unspecified."}, "accounts": {"type": "array", "description": "Applies a filter limit to creators who meet the account-specific thresholds specified for a particular social platform. Defaults to all accounts if not specified.", "items": {"type": "object", "required": ["platform"], "properties": {"platform": {"type": "string", "x-component": "select", "description": "The platform name identifier associated with this account filter.", "x-options": {"youtube": "YouTube", "facebook": "Facebook", "instagram": "Instagram", "twitch": "Twitch", "tiktok": "TikTok"}}, "audience_min_male": {"type": "number", "format": "double", "description": "Applies a minimum threshold to creators whose platform audience is male. Specifying a value of 26.4, for example, means that a minimum of 26.4% of the platform audience for the creator must be male. This filter parameter is currently only available for the YouTube and Facebook platforms. Defaults to the full range if not specified."}, "audience_min_female": {"type": "number", "format": "double", "description": "Applies a minimum threshold to creators whose platform audience is female. Specifying a value of 32.1, for example, means that a minimum of 32.1% of the platform audience for the creator must be female. This filter parameter is currently only available for the YouTube and Facebook platforms. Defaults to the full range if not specified."}, "audience_age_range": {"type": "object", "description": "Applies an age range limit for the creator's platform audience to use in the filter. Note that only certain age values are currently allowed by the audience_age_range parameter. The allowable values include the following - 13, 18, 25, 35, 45, 55 Specifying either a min or max value for this parameter outside of the allowable values listed above will return an error. This filter parameter is currently only available for the YouTube and Facebook platforms. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "audience_min_age_range": {"type": "number", "format": "double", "description": "Applies a minimum threshold to the audience_age_range parameter. Specifying a value of 22.2 when audience_age_range is set to ages between 18 to 25, for example, means that a minimum of 22.2% of the platform audience for the creator must be between the ages of 18 to 25. Note that this parameter is intended to be used in conjunction with the audience_age_range parameter and will otherwise be ignored. This filter parameter is currently only supported for the YouTube and Facebook platforms. Defaults to the full range if not specified"}, "audience_locations": {"type": "array", "items": {"type": "object", "properties": {"country": {"type": "string", "description": "Specifies the country as a two-letter ISO 3166-1 alpha-2 code associated with this filter. Note that this parameter must be used in conjunction with the parameter and will otherwise be ignored. This filter parameter is currently only available for the Facebook and YouTube platforms.", "x-component": "select", "x-autocomplete": "qb/getCountries"}, "min": {"type": "number", "format": "double", "description": "Applies a minimum threshold to the parameter. Specifying a value of 20.5 when the parameter is set to \"de\", for example, means that a minimum of 20.5% of the platform audience for the creator must be located in Germany. Note that this parameter must be used in conjunction with the parameter and will otherwise be ignored. This filter parameter is currently only available for the Facebook and YouTube platforms."}}}}, "followers": {"type": "object", "description": "Applies a follower, subscriber (in the case of YouTube) or Facebook page like a range limit for the creator's platform account to use in the filter. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "views": {"type": "object", "description": "Applies a views range limit for the creator's platform account to use in the filter. This filter parameter is currently only available for the Facebook, Instagram, and YouTube platforms. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "monthly_views": {"type": "object", "description": "Applies the last month views range limit for the creator's platform account to use in the filter. This filter parameter is currently only available for all platforms except Twitch. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "v30": {"type": "object", "description": "Applies a v30 range limit for the creator's platform account to use in the filter. Refer to Tubular Video Ratings documentation for details on how v30 is calculated. This filter parameter is currently only available for the Facebook, Tiktok, Instagram, and YouTube platforms. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}}}}}}}}}}}}}, "responses": {"200": {"description": "Status of operation", "headers": {"Tubular-RateLimit-Overall-Limit": {"description": "The overall rate limit is 60 requests per minute. This rate limit applies to any combination of API methods that are called within a trailing 1-minute timeframe.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Overall-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Limit": {"description": "The concurrency rate limit is set to 1. This means that no more than a single request can be made at a time (i.e., in parallel). Attempting to issue a video.search request while a video.facets request is still running, for example will cause the video.search request to return a rate_limited error.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Remaining": {"description": "Number of concurrent requests available for use.", "schema": {"type": "integer"}}, "Tubular-Quota-Rows-Consumed": {"description": "Number of rows consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Consumed": {"description": "Number of quota units consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Limit": {"description": "Total quota units available for the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Remaining": {"description": "Number of quota units remaining in the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Expires-After": {"description": "Date and time when the current quota period ends.", "schema": {"type": "string", "format": "date-time"}}, "Tubular-RateLimit-FacetSummary-Limit": {"description": "All aggregated request for either creators or videos are inherently expensive. Because of this, Tubular places a limit of no more than 6 total facet and summary requests per minute.", "schema": {"type": "integer"}}, "Tubular-RateLimit-FacetSummary-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"type": "object", "properties": {"ok": {"type": "boolean", "description": "Standard API response for success/failure."}, "month": {"type": "string", "description": "The month in \"YYYY-MM\" format for which the monthly metrics apply to."}, "summary": {"type": "array", "description": "A list of objects depicting a by-platform breakdown of summary statistics for the given query filter.", "items": {"type": "object", "properties": {"platform": {"type": "string", "description": "The platform name identifier."}, "num_creators": {"type": "integer", "description": "Number of creators associated with the current social platform."}, "total_videos": {"type": "integer", "description": "Total uploaded videos for the query across the current social platform."}, "total_views": {"type": "integer", "description": "Total views for the query across the current social platform."}, "total_engagements": {"type": "integer", "description": "Total ngagements for the query across the current social platform."}, "total_followers": {"type": "integer", "description": "Total followers for the query across the current social platform (specifically, subscribers for Youtube, page likes for Facebook and followers for other platforms)."}, "monthly_views": {"type": "integer", "description": "This metric is computed using the last available month of views. Refer to the month parameter to see which month this represents."}, "monthly_engagements": {"type": "integer", "description": "This metric is computed using the last available month of engagements. Refer to the month parameter to see which month this represents."}, "monthly_followers": {"type": "integer", "description": "This metric is computed using the last available month of followers. Refer to the month parameter to see which month this represents."}, "v30_avg": {"type": "number", "format": "double", "description": "Average v30 for the current query across the current social platform. Refer to Tubular Video Ratings documentation for details on how v30 is calculated. This metric is computed using the last available month of views."}, "e30_avg": {"type": "number", "format": "double", "description": "Average e30 for the current query across the current social platform. Refer to Tubular Video Ratings documentation for details on how e30 is calculated. This metric is computed using the last available month of views."}, "er30_avg": {"type": "number", "format": "double", "description": "Average v30 for the current query across the current social platform. Refer to Tubular Video Ratings documentation for details on how er30 is calculated. This metric is computed using the last available month of views."}}}}}}}}}, "429": {"description": "The query is rate-limited.", "headers": {"Tubular-RateLimit-Overall-Limit": {"description": "The overall rate limit is 60 requests per minute. This rate limit applies to any combination of API methods that are called within a trailing 1-minute timeframe.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Overall-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Limit": {"description": "The concurrency rate limit is set to 1. This means that no more than a single request can be made at a time (i.e., in parallel). Attempting to issue a video.search request while a video.facets request is still running, for example will cause the video.search request to return a rate_limited error.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Remaining": {"description": "Number of concurrent requests available for use.", "schema": {"type": "integer"}}, "Tubular-Quota-Rows-Consumed": {"description": "Number of rows consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Consumed": {"description": "Number of quota units consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Limit": {"description": "Total quota units available for the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Remaining": {"description": "Number of quota units remaining in the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Expires-After": {"description": "Date and time when the current quota period ends.", "schema": {"type": "string", "format": "date-time"}}, "Tubular-RateLimit-FacetSummary-Limit": {"description": "All aggregated request for either creators or videos are inherently expensive. Because of this, Tubular places a limit of no more than 6 total facet and summary requests per minute.", "schema": {"type": "integer"}}, "Tubular-RateLimit-FacetSummary-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}}}}}}, "/creator.facets": {"x-requires": ["api_intelligence"], "x-group": ["data", "creator"], "post": {"summary": "Returns a list of up to the top 50 creator filter facets (aggregations) pertaining to a particular creator search query.", "parameters": [{"in": "header", "description": "Tubular API key.", "name": "Api-Key", "schema": {"type": "string"}}], "requestBody": {"content": {"application/json": {"schema": {"type": "object", "required": ["query", "facets"], "properties": {"query": {"type": "object", "description": "Defines search criteria that combines include and exclude filters.", "properties": {"savedsearch_id": {"type": "integer", "x-component": "select", "description": "Creator saved search id", "x-source": "qb/getCreatorSavedSearches"}, "include_filter": {"type": "object", "description": "A creator filter to be included by the query. Defaults to include everything if not specified.", "properties": {"search": {"type": "string", "description": "The search text string to be included in the filter for searching across creator names and themes. This string may include optional boolean search operators as described by the Help Center. Defaults to empty string if not specified.", "x-hint": "Use AND and OR operators", "x-placeholder": null}, "creators": {"type": "array", "x-component": "select", "x-autocomplete": "qb/searchCreators", "x-add": true, "description": "A list of one or more creator identifiers representing the creators that should be retrieved.", "items": {"type": "string"}}, "creator_types": {"type": "array", "description": "An array of creator types to use in the filter.", "x-component": "select", "x-options": {"influencer": "Influencer", "brand": "Brand", "media company": "Media Company", "aggregator": "Aggregator"}, "items": {"type": "string"}}, "creator_platforms": {"type": "array", "x-component": "select", "description": "An array of social platforms to use in the filter.", "x-options": {"youtube": "YouTube", "facebook": "Facebook", "instagram": "Instagram", "twitch": "Twitch", "tiktok": "TikTok"}, "items": {"type": "string"}}, "creator_genres": {"type": "array", "description": "An array of content genre identifiers to use in the filter. Available content genre identifiers can be obtained via a VideoFacets query. Defaults to all content genres if not specified.", "x-component": "select", "x-options": {"2": "Travel", "3": "Music & Dance", "4": "Sports", "5": "Animals & Pets", "7": "People & Blogs", "9": "Cars, Trucks & Racing", "11": "Business", "13": "Kids Entertainment & Animation", "14": "Education", "15": "Food & Drink", "16": "Fashion & Style", "19": "Health, Fitness & Self Help", "21": "Home & DIY", "22": "News & Politics", "23": "Beauty", "24": "Film & Movies", "27": "Gaming", "32": "Family & Parenting", "33": "Science & Tech", "36": "Entertainment", "37": "General Interest"}, "items": {"type": "integer"}}, "creator_countries": {"type": "array", "description": "Specifies the countries associated with the creator's accounts when limiting videos (e.g., only videos whose accounts are associated with the United States and France). Available creator countries can be obtained via a VideoFacets query. Country strings are represented as two-letter ISO 3166-1 alpha-2 codes. Defaults to all countries if not specified.", "items": {"type": "string"}, "x-component": "select", "x-autocomplete": "qb/getCountries"}, "creator_languages": {"type": "array", "description": "Specifies the dominant language of the creator to use in the filter. Languages are represented as ISO 639-1 two-letter language codes (for e.g. en, ja, es). Defaults to all languages if not specified.", "items": {"type": "string"}, "x-component": "select", "x-autocomplete": "qb/getLanguages"}, "creator_industries": {"type": "array", "description": "An array of creator industry identifiers to use in the filter. Defaults to all creator industries if not specified. Relevant for Brands.", "x-component": "select", "x-options": {"1": "Technology", "2": "Travel & Leisure", "3": "Music", "4": "CPG", "5": "Automotive", "6": "Financial & Insurance", "7": "Toys & Board Games", "8": "Media", "9": "Retail", "10": "Logistics & Heavy Industry", "11": "Other", "12": "Apparel & Accessories", "13": "Beverages", "14": "Personal Care & Health", "15": "Education", "16": "Public Service & Nonprofit", "17": "Food", "19": "Telecom", "20": "Pets", "21": "Sports Teams & Leagues", "22": "Gaming", "23": "Energy", "25": "Electronics", "27": "Broadcast, Cable, Radio, Film", "28": "Digital First Media", "29": "Magazine & Newspaper", "30": "Beauty"}, "items": {"type": "integer"}}, "creator_properties": {"type": "array", "x-component": "select", "description": "An array of creator property identifiers to use in the filter. Available creator properties can be obtained via a VideoFacets query. Defaults to all creator properties if not specified.", "x-autocomplete": "qb/searchProperties", "items": {"type": "integer"}}, "creator_list": {"type": "integer", "description": "A creator custom list identifier to use in the filter. A creator list represents a custom list of creators. These custom lists can be created and modified programmatically. See the Custom List section of the API documentation for more details. Available creator lists can be obtained via the custom_list.enumerate method. Defaults to not include a creator list.", "x-component": "select", "x-source": "qb/getCreatorLists"}, "creator_last_upload": {"type": "string", "x-component": "select", "description": "Applies a relative date filter to the number of days from the current day when a video was last uploaded by a creator. Note that the upload date is determined by the time in UTC that the video was uploaded. Defaults to all available data if not specified.", "x-options": {"last_7": "Last 7 days", "last_30": "Last 30 days", "last_90": "Last 90 days"}}, "creator_views": {"type": "object", "x-component": "integerRange", "description": "Applies a view limit (total number of views across all accounts for the previous month) to use in the filter. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "creator_rising_star": {"type": "boolean", "description": "Specifies whether to limit the filter to creators who are identified by Tubular as rising stars. If not specified, then all creators are included (i.e., both rising and non-rising stars)."}, "creator_facebook_watch": {"type": "boolean", "description": "Specifies whether to limit the filter to creators who publish a show on Facebook watch. If not specified, then all creators are included (i.e., both Facebook watch creators and non-Facebook watch creators.) Value can only be true or unspecified."}, "accounts": {"type": "array", "description": "Applies a filter limit to creators who meet the account-specific thresholds specified for a particular social platform. Defaults to all accounts if not specified.", "items": {"type": "object", "required": ["platform"], "properties": {"platform": {"type": "string", "x-component": "select", "description": "The platform name identifier associated with this account filter.", "x-options": {"youtube": "YouTube", "facebook": "Facebook", "instagram": "Instagram", "twitch": "Twitch", "tiktok": "TikTok"}}, "audience_min_male": {"type": "number", "format": "double", "description": "Applies a minimum threshold to creators whose platform audience is male. Specifying a value of 26.4, for example, means that a minimum of 26.4% of the platform audience for the creator must be male. This filter parameter is currently only available for the YouTube and Facebook platforms. Defaults to the full range if not specified."}, "audience_min_female": {"type": "number", "format": "double", "description": "Applies a minimum threshold to creators whose platform audience is female. Specifying a value of 32.1, for example, means that a minimum of 32.1% of the platform audience for the creator must be female. This filter parameter is currently only available for the YouTube and Facebook platforms. Defaults to the full range if not specified."}, "audience_age_range": {"type": "object", "description": "Applies an age range limit for the creator's platform audience to use in the filter. Note that only certain age values are currently allowed by the audience_age_range parameter. The allowable values include the following - 13, 18, 25, 35, 45, 55 Specifying either a min or max value for this parameter outside of the allowable values listed above will return an error. This filter parameter is currently only available for the YouTube and Facebook platforms. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "audience_min_age_range": {"type": "number", "format": "double", "description": "Applies a minimum threshold to the audience_age_range parameter. Specifying a value of 22.2 when audience_age_range is set to ages between 18 to 25, for example, means that a minimum of 22.2% of the platform audience for the creator must be between the ages of 18 to 25. Note that this parameter is intended to be used in conjunction with the audience_age_range parameter and will otherwise be ignored. This filter parameter is currently only supported for the YouTube and Facebook platforms. Defaults to the full range if not specified"}, "audience_locations": {"type": "array", "items": {"type": "object", "properties": {"country": {"type": "string", "description": "Specifies the country as a two-letter ISO 3166-1 alpha-2 code associated with this filter. Note that this parameter must be used in conjunction with the parameter and will otherwise be ignored. This filter parameter is currently only available for the Facebook and YouTube platforms.", "x-component": "select", "x-autocomplete": "qb/getCountries"}, "min": {"type": "number", "format": "double", "description": "Applies a minimum threshold to the parameter. Specifying a value of 20.5 when the parameter is set to \"de\", for example, means that a minimum of 20.5% of the platform audience for the creator must be located in Germany. Note that this parameter must be used in conjunction with the parameter and will otherwise be ignored. This filter parameter is currently only available for the Facebook and YouTube platforms."}}}}, "followers": {"type": "object", "description": "Applies a follower, subscriber (in the case of YouTube) or Facebook page like a range limit for the creator's platform account to use in the filter. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "views": {"type": "object", "description": "Applies a views range limit for the creator's platform account to use in the filter. This filter parameter is currently only available for the Facebook, Instagram, and YouTube platforms. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "monthly_views": {"type": "object", "description": "Applies the last month views range limit for the creator's platform account to use in the filter. This filter parameter is currently only available for all platforms except Twitch. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "v30": {"type": "object", "description": "Applies a v30 range limit for the creator's platform account to use in the filter. Refer to Tubular Video Ratings documentation for details on how v30 is calculated. This filter parameter is currently only available for the Facebook, Tiktok, Instagram, and YouTube platforms. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}}}}}}, "exclude_filter": {"type": "object", "description": "A creator filter to be excluded by the query. Defaults to exclude no videos if not specified.", "properties": {"search": {"type": "string", "description": "The search text string to be included in the filter for searching across creator names and themes. This string may include optional boolean search operators as described by the Help Center. Defaults to empty string if not specified.", "x-hint": "Use AND and OR operators", "x-placeholder": null}, "creators": {"type": "array", "x-component": "select", "x-autocomplete": "qb/searchCreators", "x-add": true, "description": "A list of one or more creator identifiers representing the creators that should be retrieved.", "items": {"type": "string"}}, "creator_types": {"type": "array", "description": "An array of creator types to use in the filter.", "x-component": "select", "x-options": {"influencer": "Influencer", "brand": "Brand", "media company": "Media Company", "aggregator": "Aggregator"}, "items": {"type": "string"}}, "creator_platforms": {"type": "array", "x-component": "select", "description": "An array of social platforms to use in the filter.", "x-options": {"youtube": "YouTube", "facebook": "Facebook", "instagram": "Instagram", "twitch": "Twitch", "tiktok": "TikTok"}, "items": {"type": "string"}}, "creator_genres": {"type": "array", "description": "An array of content genre identifiers to use in the filter. Available content genre identifiers can be obtained via a VideoFacets query. Defaults to all content genres if not specified.", "x-component": "select", "x-options": {"2": "Travel", "3": "Music & Dance", "4": "Sports", "5": "Animals & Pets", "7": "People & Blogs", "9": "Cars, Trucks & Racing", "11": "Business", "13": "Kids Entertainment & Animation", "14": "Education", "15": "Food & Drink", "16": "Fashion & Style", "19": "Health, Fitness & Self Help", "21": "Home & DIY", "22": "News & Politics", "23": "Beauty", "24": "Film & Movies", "27": "Gaming", "32": "Family & Parenting", "33": "Science & Tech", "36": "Entertainment", "37": "General Interest"}, "items": {"type": "integer"}}, "creator_countries": {"type": "array", "description": "Specifies the countries associated with the creator's accounts when limiting videos (e.g., only videos whose accounts are associated with the United States and France). Available creator countries can be obtained via a VideoFacets query. Country strings are represented as two-letter ISO 3166-1 alpha-2 codes. Defaults to all countries if not specified.", "items": {"type": "string"}, "x-component": "select", "x-autocomplete": "qb/getCountries"}, "creator_languages": {"type": "array", "description": "Specifies the dominant language of the creator to use in the filter. Languages are represented as ISO 639-1 two-letter language codes (for e.g. en, ja, es). Defaults to all languages if not specified.", "items": {"type": "string"}, "x-component": "select", "x-autocomplete": "qb/getLanguages"}, "creator_industries": {"type": "array", "description": "An array of creator industry identifiers to use in the filter. Defaults to all creator industries if not specified. Relevant for Brands.", "x-component": "select", "x-options": {"1": "Technology", "2": "Travel & Leisure", "3": "Music", "4": "CPG", "5": "Automotive", "6": "Financial & Insurance", "7": "Toys & Board Games", "8": "Media", "9": "Retail", "10": "Logistics & Heavy Industry", "11": "Other", "12": "Apparel & Accessories", "13": "Beverages", "14": "Personal Care & Health", "15": "Education", "16": "Public Service & Nonprofit", "17": "Food", "19": "Telecom", "20": "Pets", "21": "Sports Teams & Leagues", "22": "Gaming", "23": "Energy", "25": "Electronics", "27": "Broadcast, Cable, Radio, Film", "28": "Digital First Media", "29": "Magazine & Newspaper", "30": "Beauty"}, "items": {"type": "integer"}}, "creator_properties": {"type": "array", "x-component": "select", "description": "An array of creator property identifiers to use in the filter. Available creator properties can be obtained via a VideoFacets query. Defaults to all creator properties if not specified.", "x-autocomplete": "qb/searchProperties", "items": {"type": "integer"}}, "creator_list": {"type": "integer", "description": "A creator custom list identifier to use in the filter. A creator list represents a custom list of creators. These custom lists can be created and modified programmatically. See the Custom List section of the API documentation for more details. Available creator lists can be obtained via the custom_list.enumerate method. Defaults to not include a creator list.", "x-component": "select", "x-source": "qb/getCreatorLists"}, "creator_last_upload": {"type": "string", "x-component": "select", "description": "Applies a relative date filter to the number of days from the current day when a video was last uploaded by a creator. Note that the upload date is determined by the time in UTC that the video was uploaded. Defaults to all available data if not specified.", "x-options": {"last_7": "Last 7 days", "last_30": "Last 30 days", "last_90": "Last 90 days"}}, "creator_views": {"type": "object", "x-component": "integerRange", "description": "Applies a view limit (total number of views across all accounts for the previous month) to use in the filter. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "creator_rising_star": {"type": "boolean", "description": "Specifies whether to limit the filter to creators who are identified by Tubular as rising stars. If not specified, then all creators are included (i.e., both rising and non-rising stars)."}, "creator_facebook_watch": {"type": "boolean", "description": "Specifies whether to limit the filter to creators who publish a show on Facebook watch. If not specified, then all creators are included (i.e., both Facebook watch creators and non-Facebook watch creators.) Value can only be true or unspecified."}, "accounts": {"type": "array", "description": "Applies a filter limit to creators who meet the account-specific thresholds specified for a particular social platform. Defaults to all accounts if not specified.", "items": {"type": "object", "required": ["platform"], "properties": {"platform": {"type": "string", "x-component": "select", "description": "The platform name identifier associated with this account filter.", "x-options": {"youtube": "YouTube", "facebook": "Facebook", "instagram": "Instagram", "twitch": "Twitch", "tiktok": "TikTok"}}, "audience_min_male": {"type": "number", "format": "double", "description": "Applies a minimum threshold to creators whose platform audience is male. Specifying a value of 26.4, for example, means that a minimum of 26.4% of the platform audience for the creator must be male. This filter parameter is currently only available for the YouTube and Facebook platforms. Defaults to the full range if not specified."}, "audience_min_female": {"type": "number", "format": "double", "description": "Applies a minimum threshold to creators whose platform audience is female. Specifying a value of 32.1, for example, means that a minimum of 32.1% of the platform audience for the creator must be female. This filter parameter is currently only available for the YouTube and Facebook platforms. Defaults to the full range if not specified."}, "audience_age_range": {"type": "object", "description": "Applies an age range limit for the creator's platform audience to use in the filter. Note that only certain age values are currently allowed by the audience_age_range parameter. The allowable values include the following - 13, 18, 25, 35, 45, 55 Specifying either a min or max value for this parameter outside of the allowable values listed above will return an error. This filter parameter is currently only available for the YouTube and Facebook platforms. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "audience_min_age_range": {"type": "number", "format": "double", "description": "Applies a minimum threshold to the audience_age_range parameter. Specifying a value of 22.2 when audience_age_range is set to ages between 18 to 25, for example, means that a minimum of 22.2% of the platform audience for the creator must be between the ages of 18 to 25. Note that this parameter is intended to be used in conjunction with the audience_age_range parameter and will otherwise be ignored. This filter parameter is currently only supported for the YouTube and Facebook platforms. Defaults to the full range if not specified"}, "audience_locations": {"type": "array", "items": {"type": "object", "properties": {"country": {"type": "string", "description": "Specifies the country as a two-letter ISO 3166-1 alpha-2 code associated with this filter. Note that this parameter must be used in conjunction with the parameter and will otherwise be ignored. This filter parameter is currently only available for the Facebook and YouTube platforms.", "x-component": "select", "x-autocomplete": "qb/getCountries"}, "min": {"type": "number", "format": "double", "description": "Applies a minimum threshold to the parameter. Specifying a value of 20.5 when the parameter is set to \"de\", for example, means that a minimum of 20.5% of the platform audience for the creator must be located in Germany. Note that this parameter must be used in conjunction with the parameter and will otherwise be ignored. This filter parameter is currently only available for the Facebook and YouTube platforms."}}}}, "followers": {"type": "object", "description": "Applies a follower, subscriber (in the case of YouTube) or Facebook page like a range limit for the creator's platform account to use in the filter. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "views": {"type": "object", "description": "Applies a views range limit for the creator's platform account to use in the filter. This filter parameter is currently only available for the Facebook, Instagram, and YouTube platforms. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "monthly_views": {"type": "object", "description": "Applies the last month views range limit for the creator's platform account to use in the filter. This filter parameter is currently only available for all platforms except Twitch. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}, "v30": {"type": "object", "description": "Applies a v30 range limit for the creator's platform account to use in the filter. Refer to Tubular Video Ratings documentation for details on how v30 is calculated. This filter parameter is currently only available for the Facebook, Tiktok, Instagram, and YouTube platforms. Defaults to the full range if not specified.", "properties": {"min": {"type": "integer", "description": "The minimum value to be included as part of a range of integer values."}, "max": {"type": "integer", "description": "The maximum value to be included as part of a range of integer values."}}}}}}}}}}, "facets": {"type": "array", "description": "A list of metrics.", "x-component": "select", "items": {"type": "string"}, "x-options": {"creator_types": "Creator Types", "creator_platforms": "Creator Platforms", "creator_genres": "Creator Genres", "creator_countries": "Creator Countries", "creator_languages": "Creator Languages", "creator_industries": "Creator Industries", "creator_properties": "Creator Properties", "creator_themes": "Creator Themes"}}}}}}}, "responses": {"200": {"description": "Status of operation", "headers": {"Tubular-RateLimit-Overall-Limit": {"description": "The overall rate limit is 60 requests per minute. This rate limit applies to any combination of API methods that are called within a trailing 1-minute timeframe.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Overall-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Limit": {"description": "The concurrency rate limit is set to 1. This means that no more than a single request can be made at a time (i.e., in parallel). Attempting to issue a video.search request while a video.facets request is still running, for example will cause the video.search request to return a rate_limited error.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Remaining": {"description": "Number of concurrent requests available for use.", "schema": {"type": "integer"}}, "Tubular-Quota-Rows-Consumed": {"description": "Number of rows consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Consumed": {"description": "Number of quota units consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Limit": {"description": "Total quota units available for the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Remaining": {"description": "Number of quota units remaining in the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Expires-After": {"description": "Date and time when the current quota period ends.", "schema": {"type": "string", "format": "date-time"}}, "Tubular-RateLimit-FacetSummary-Limit": {"description": "All aggregated request for either creators or videos are inherently expensive. Because of this, Tubular places a limit of no more than 6 total facet and summary requests per minute.", "schema": {"type": "integer"}}, "Tubular-RateLimit-FacetSummary-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"type": "object", "properties": {"ok": {"type": "boolean", "description": "Standard API response for success/failure."}, "facets": {"type": "array", "description": "A list of facets associated with the requested filters.", "items": {"type": "object", "properties": {"filter": {"type": "string", "description": "The filter name pertaining to the list of facet metrics provided by this object."}, "metrics": {"type": "array", "description": "A list of creator facet metrics for a particular filter ordered descending by count.", "items": {"type": "object", "properties": {"id": {"type": "integer", "description": "Facet identifier for the current facet. A facet id is guaranteed to be globally unique for a particular filter type (e.g., no two facets will ever use the same id across all creator_properties)."}, "count": {"type": "integer", "description": "The distinct count of unique occurrences for a particular facet value and filter query combination."}, "title": {"type": "string", "description": "The title of a particular facet value. This is intended to be for display purposes only. A null value means that the facet id should also be used for display purposes (e.g., for \"creator_platforms\" and \"creator_types\")."}}}}}}}}}}}}, "429": {"description": "The query is rate-limited.", "headers": {"Tubular-RateLimit-Overall-Limit": {"description": "The overall rate limit is 60 requests per minute. This rate limit applies to any combination of API methods that are called within a trailing 1-minute timeframe.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Overall-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Limit": {"description": "The concurrency rate limit is set to 1. This means that no more than a single request can be made at a time (i.e., in parallel). Attempting to issue a video.search request while a video.facets request is still running, for example will cause the video.search request to return a rate_limited error.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Remaining": {"description": "Number of concurrent requests available for use.", "schema": {"type": "integer"}}, "Tubular-Quota-Rows-Consumed": {"description": "Number of rows consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Consumed": {"description": "Number of quota units consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Limit": {"description": "Total quota units available for the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Remaining": {"description": "Number of quota units remaining in the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Expires-After": {"description": "Date and time when the current quota period ends.", "schema": {"type": "string", "format": "date-time"}}, "Tubular-RateLimit-FacetSummary-Limit": {"description": "All aggregated request for either creators or videos are inherently expensive. Because of this, Tubular places a limit of no more than 6 total facet and summary requests per minute.", "schema": {"type": "integer"}}, "Tubular-RateLimit-FacetSummary-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}}}}}}, "/creator.audience_overlap": {"x-requires": ["api_intelligence"], "x-group": ["data", "creator", "audience"], "post": {"summary": "Find videos or creators that are also watched by the audience of the source creators.", "parameters": [{"in": "header", "description": "Tubular API key.", "name": "Api-Key", "schema": {"type": "string"}}], "requestBody": {"content": {"application/json": {"schema": {"type": "object", "required": ["creator_ids", "type", "platform"], "properties": {"creator_ids": {"type": "array", "x-component": "select", "x-autocomplete": "qb/searchCreators", "x-add": true, "description": "A list of creator identifiers representing the creators that the audience overlap should be calculated against.", "items": {"type": "string"}}, "type": {"type": "string", "x-component": "select", "description": "Specifies whether to calculate a list of either videos or creators the audience of the specified video_ids also watches.", "x-options": {"video": "Video", "creator": "Creator"}}, "platform": {"type": "string", "x-component": "select", "description": "Tubular requires specification of platform for this analysis because each platform has its own \"universe\" of audience members. These universes are not equal, either in terms of size or user behavior, so even if we tried to link audience members across platforms (which we do not), any type of cross-platform analysis would bias towards one platform or another.", "x-options": {"youtube": "YouTube", "facebook": "Facebook", "instagram": "Instagram"}}, "result_ids": {"type": "array", "x-component": "select", "x-add": true, "x-hint": "To add an item, type creator or video ID and press enter", "description": "A list of creator or video IDs allowed in the results.", "items": {"type": "string"}}, "sort": {"type": "object", "description": "The sort order to use when returning a list of videos or creators whose audience overlaps a particular list of videos. This parameter will default to sort descending by \"score\" if not specified. Refer to the AudienceOverlapSort documentation below for more details on available sort options.", "properties": {"sort_by": {"type": "string", "x-component": "select", "description": "Sort results by the given metric", "x-options": {"score": {"label": "Score", "description": "A blend of overlap and affinity scores, presented because usually the most \"interesting\" results have both high overlap and high affinity, and so sorting by this metric is recommended for most cases. High affinity and low overlap tends to reveal small, non-influential entities. High overlap and low affinity tends to reveal large channels that may not be tightly correlated with the source channels or videos."}, "affinity": {"label": "Affinity", "description": "We define this to be the \"increase in likelihood that a user is to be an audience member of the discovered entity given that he/she is in the audience of the source creators or videos\". This value is reciprocal, meaning that you also read that in the opposite direction (swapping \"discovered entity\" and \"source creators or videos\") and it holds true. Think of this as a correlation score. There is no upper bound on this value; higher values simply indicate a stronger correlation between the source creators or videos and the discovered entity."}, "overlap": {"label": "Overlap", "description": "The portion of the source audience that is also an audience member of the result (creator or video). Note that this portion is expressed over the range [0,1], so a value of 0.04 means 4%. Also be aware that in general, overlap numbers will be much smaller for video overlap queries, since audience sizes for individual videos are understandably smaller than those for overall channels."}}}}}, "limit": {"type": "integer", "description": "Limit the number of results. Default is 2000."}}}}}}, "responses": {"200": {"description": "Status of operation", "headers": {"Tubular-RateLimit-Overall-Limit": {"description": "The overall rate limit is 60 requests per minute. This rate limit applies to any combination of API methods that are called within a trailing 1-minute timeframe.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Overall-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Limit": {"description": "The concurrency rate limit is set to 1. This means that no more than a single request can be made at a time (i.e., in parallel). Attempting to issue a video.search request while a video.facets request is still running, for example will cause the video.search request to return a rate_limited error.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Remaining": {"description": "Number of concurrent requests available for use.", "schema": {"type": "integer"}}, "Tubular-Quota-Rows-Consumed": {"description": "Number of rows consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Consumed": {"description": "Number of quota units consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Limit": {"description": "Total quota units available for the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Remaining": {"description": "Number of quota units remaining in the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Expires-After": {"description": "Date and time when the current quota period ends.", "schema": {"type": "string", "format": "date-time"}}, "Tubular-RateLimit-AudienceOverlap-Limit": {"description": "Audience overlap queries are computationally expensive. Because of this, Tubular places a limit of no more than 1 audience overlap query per minute.", "schema": {"type": "integer"}}, "Tubular-RateLimit-AudienceOverlap-Remaining": {"description": "A number of aduence overlap calls left to be made within the minute timeframe.", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"type": "object", "properties": {"ok": {"type": "boolean", "description": "Standard API response for success/failure."}, "results": {"type": "array", "description": "A list of objects representing either creators or videos (depending on the type of overlap requested) also watched by audience members of the source IDs. Up to 2,000 results will be returned, sorted by the requested sort parameter.", "items": {"type": "object", "properties": {"affinity": {"type": "number", "format": "double", "description": "Defined as \"the increase in likelihood that a user is to be an audience member of the discovered entity given that he/she is in the audience of the source creators.\" This value is reciprocal, meaning that you can also read this definition in the opposite direction (i.e., swapping \"discovered entity\" and \"source creators\") and it will also hold true. This can be thought of as a correlation score. There is no upper bound on this value; higher values simply indicate a stronger correlation between the source creators and the discovered entity."}, "overlap": {"type": "number", "format": "double", "description": "The portion of the source audience that is also an audience member of the result (creator or video). Note that this portion is expressed over the range [0,1], so a value of 0.04 means 4%. Also be aware that, in general, overlap numbers will be much smaller for video overlap queries, since audience sizes for individual videos are understandably smaller than those for overall channels."}, "score": {"type": "number", "format": "double", "description": "A blend of overlap and affinity scores, presented because usually the most \"interesting\" results have both high overlap and high affinity. High affinity and low overlap tends to reveal small, non-influential entities. High overlap and low affinity tends to reveal large channels that may not be tightly correlated with the source creators."}, "creator_id": {"type": "string", "description": "The creator identifier associated with the overlap result (note that this will only be returned if the overlap type requested is of type \"creator\")."}, "video_id": {"type": "object", "description": "The video identifier associated with the overlap result (note that this will only be returned if the overlap type requested is of type \"video\").", "properties": {"platform": {"type": "string", "description": "The social platform for the video.", "x-options": {"youtube": "YouTube", "facebook": "Facebook", "instagram": "Instagram", "twitch": "Twitch"}}, "id": {"type": "string", "description": "A platform-specific unique identifier tied to the video. Typically, this identifier is also included by the social platform URL where a video can be viewed (e.g., the URL \"https://www.youtube.com/watch?v=abc123\" for video id \"abc123\" is used to refer to a YouTube video with that id)."}}}}}}}}}}}, "429": {"description": "The query is rate-limited.", "headers": {"Tubular-RateLimit-Overall-Limit": {"description": "The overall rate limit is 60 requests per minute. This rate limit applies to any combination of API methods that are called within a trailing 1-minute timeframe.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Overall-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Limit": {"description": "The concurrency rate limit is set to 1. This means that no more than a single request can be made at a time (i.e., in parallel). Attempting to issue a video.search request while a video.facets request is still running, for example will cause the video.search request to return a rate_limited error.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Remaining": {"description": "Number of concurrent requests available for use.", "schema": {"type": "integer"}}, "Tubular-Quota-Rows-Consumed": {"description": "Number of rows consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Consumed": {"description": "Number of quota units consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Limit": {"description": "Total quota units available for the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Remaining": {"description": "Number of quota units remaining in the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Expires-After": {"description": "Date and time when the current quota period ends.", "schema": {"type": "string", "format": "date-time"}}, "Tubular-RateLimit-AudienceOverlap-Limit": {"description": "Audience overlap queries are computationally expensive. Because of this, Tubular places a limit of no more than 1 audience overlap query per minute.", "schema": {"type": "integer"}}, "Tubular-RateLimit-AudienceOverlap-Remaining": {"description": "A number of aduence overlap calls left to be made within the minute timeframe.", "schema": {"type": "integer"}}}}}}}, "/creator.ratings": {"x-requires": ["api_premium"], "x-group": ["data", "audience", "creator"], "post": {"summary": "Get Tubular Audience Ratings (T.A.R.) monthly metrics (uniques, watchtime etc.) for one or more creators optionally segmented by demographic groups.", "parameters": [{"in": "header", "description": "Tubular API key.", "name": "Api-Key", "schema": {"type": "string"}}], "requestBody": {"content": {"application/json": {"schema": {"type": "object", "required": ["query"], "properties": {"query": {"type": "object", "description": "Defines search criteria that combines include and exclude filters.", "properties": {"included": {"type": "object", "description": "A creator filter to be included by the query. Defaults to include everything if not specified.", "properties": {"creator_types": {"type": "array", "description": "An array of creator types to use in the filter.", "x-component": "select", "x-options": {"influencer": "Influencer", "brand": "Brand", "media company": "Media Company", "aggregator": "Aggregator"}, "items": {"type": "string"}}, "creator_industries": {"type": "array", "description": "An array of creator industry identifiers to use in the filter. Defaults to all creator industries if not specified. Relevant for Brands.", "x-component": "select", "x-options": {"1": "Technology", "2": "Travel & Leisure", "3": "Music", "4": "CPG", "5": "Automotive", "6": "Financial & Insurance", "7": "Toys & Board Games", "8": "Media", "9": "Retail", "10": "Logistics & Heavy Industry", "11": "Other", "12": "Apparel & Accessories", "13": "Beverages", "14": "Personal Care & Health", "15": "Education", "16": "Public Service & Nonprofit", "17": "Food", "19": "Telecom", "20": "Pets", "21": "Sports Teams & Leagues", "22": "Gaming", "23": "Energy", "25": "Electronics", "27": "Broadcast, Cable, Radio, Film", "28": "Digital First Media", "29": "Magazine & Newspaper", "30": "Beauty"}, "items": {"type": "integer"}}, "creator_properties": {"type": "array", "x-component": "select", "description": "An array of creator property identifiers to use in the filter. Available creator properties can be obtained via a VideoFacets query. Defaults to all creator properties if not specified.", "x-autocomplete": "qb/searchProperties", "items": {"type": "integer"}}, "creators": {"type": "array", "x-component": "select", "description": "An array of creator identifiers to use in the filter. Available creator identifiers can be obtained via the VideoFacets method or by searching for a particular creator via the CreatorSearch method. Defaults to all creators.", "x-autocomplete": "qb/searchCreators", "x-add": true, "items": {"type": "string"}}, "creator_genres": {"type": "array", "description": "An array of content genre identifiers to use in the filter. Available content genre identifiers can be obtained via a VideoFacets query. Defaults to all content genres if not specified.", "x-component": "select", "x-options": {"2": "Travel", "3": "Music & Dance", "4": "Sports", "5": "Animals & Pets", "7": "People & Blogs", "9": "Cars, Trucks & Racing", "11": "Business", "13": "Kids Entertainment & Animation", "14": "Education", "15": "Food & Drink", "16": "Fashion & Style", "19": "Health, Fitness & Self Help", "21": "Home & DIY", "22": "News & Politics", "23": "Beauty", "24": "Film & Movies", "27": "Gaming", "32": "Family & Parenting", "33": "Science & Tech", "36": "Entertainment", "37": "General Interest"}, "items": {"type": "integer"}}, "creator_countries": {"type": "array", "description": "Specifies the countries associated with the creator's accounts when limiting videos (e.g., only videos whose accounts are associated with the United States and France). Available creator countries can be obtained via a VideoFacets query. Country strings are represented as two-letter ISO 3166-1 alpha-2 codes. Defaults to all countries if not specified.", "items": {"type": "string"}, "x-component": "select", "x-autocomplete": "qb/getCountries"}}}, "excluded": {"type": "object", "description": "Defines a filter to be excluded by the query. Defaults to not exclude anything if not specified.", "properties": {"creator_types": {"type": "array", "description": "An array of creator types to use in the filter.", "x-component": "select", "x-options": {"influencer": "Influencer", "brand": "Brand", "media company": "Media Company", "aggregator": "Aggregator"}, "items": {"type": "string"}}, "creator_industries": {"type": "array", "description": "An array of creator industry identifiers to use in the filter. Defaults to all creator industries if not specified. Relevant for Brands.", "x-component": "select", "x-options": {"1": "Technology", "2": "Travel & Leisure", "3": "Music", "4": "CPG", "5": "Automotive", "6": "Financial & Insurance", "7": "Toys & Board Games", "8": "Media", "9": "Retail", "10": "Logistics & Heavy Industry", "11": "Other", "12": "Apparel & Accessories", "13": "Beverages", "14": "Personal Care & Health", "15": "Education", "16": "Public Service & Nonprofit", "17": "Food", "19": "Telecom", "20": "Pets", "21": "Sports Teams & Leagues", "22": "Gaming", "23": "Energy", "25": "Electronics", "27": "Broadcast, Cable, Radio, Film", "28": "Digital First Media", "29": "Magazine & Newspaper", "30": "Beauty"}, "items": {"type": "integer"}}, "creator_properties": {"type": "array", "x-component": "select", "description": "An array of creator property identifiers to use in the filter. Available creator properties can be obtained via a VideoFacets query. Defaults to all creator properties if not specified.", "x-autocomplete": "qb/searchProperties", "items": {"type": "integer"}}, "creators": {"type": "array", "x-component": "select", "description": "An array of creator identifiers to use in the filter. Available creator identifiers can be obtained via the VideoFacets method or by searching for a particular creator via the CreatorSearch method. Defaults to all creators.", "x-autocomplete": "qb/searchCreators", "x-add": true, "items": {"type": "string"}}, "creator_genres": {"type": "array", "description": "An array of content genre identifiers to use in the filter. Available content genre identifiers can be obtained via a VideoFacets query. Defaults to all content genres if not specified.", "x-component": "select", "x-options": {"2": "Travel", "3": "Music & Dance", "4": "Sports", "5": "Animals & Pets", "7": "People & Blogs", "9": "Cars, Trucks & Racing", "11": "Business", "13": "Kids Entertainment & Animation", "14": "Education", "15": "Food & Drink", "16": "Fashion & Style", "19": "Health, Fitness & Self Help", "21": "Home & DIY", "22": "News & Politics", "23": "Beauty", "24": "Film & Movies", "27": "Gaming", "32": "Family & Parenting", "33": "Science & Tech", "36": "Entertainment", "37": "General Interest"}, "items": {"type": "integer"}}, "creator_countries": {"type": "array", "description": "Specifies the countries associated with the creator's accounts when limiting videos (e.g., only videos whose accounts are associated with the United States and France). Available creator countries can be obtained via a VideoFacets query. Country strings are represented as two-letter ISO 3166-1 alpha-2 codes. Defaults to all countries if not specified.", "items": {"type": "string"}, "x-component": "select", "x-autocomplete": "qb/getCountries"}}}}}, "filter": {"type": "object", "properties": {"platform": {"type": "string", "x-component": "select", "description": "Return metrics for the given platform. Be default cross-platforms results are returned.", "x-options": {"youtube": "YouTube", "facebook": "Facebook"}}, "audience": {"type": "object", "description": "Defines audience segments to get metrics for.", "properties": {"ages": {"type": "array", "x-component": "select", "description": "A list of age ranges to get metrics for.", "x-options": {"13_17": "13-17", "18_24": "18-24", "25_34": "25-34", "35_44": "35-44", "45_54": "45-54", "55_plus": "55+"}, "items": {"type": "string"}}, "genders": {"type": "array", "x-component": "select", "description": "A list of genders to get metrics for.", "x-options": {"f": "Females", "m": "Males"}, "items": {"type": "string"}}, "countries": {"type": "array", "x-component": "select", "description": "A list of countries to get metrics for.", "x-options": {"US": "US", "BR": "BR", "DE": "DE", "FR": "FR", "GB": "GB", "MX": "MX", "GLOBAL": "GLOBAL"}, "items": {"type": "string"}}}}, "period": {"type": "object", "description": "Months range to get metrics for. Data is available from 2020-02 to the last full month. Some countries (DE, MX, GB) have a later start date.", "properties": {"since": {"type": "string", "x-component": "month", "x-min-month": "2020-02", "description": "Min month in YYYY-MM format. Earliest available month is 2020-02."}, "until": {"type": "string", "x-component": "month", "x-min-month": "2020-02", "description": "Max month in YYYY-MM format. By default these values are set to the last full month."}}}}}, "segmentation_attributes": {"type": "array", "x-component": "select", "description": "An attribute to segment the results by.", "items": {"type": "string"}, "x-options": {"audience": {"label": "Audience", "description": "Return results segmented by audience groups set in the filter"}}}, "sort": {"type": "object", "description": "Defines how results are sorted when multiple creators are returned. Note, that sorting applies across creators so when results are segmented by demographics or multiple months are requested, results within creator segments/months are not sorted.", "properties": {"metric": {"type": "string", "description": "Metric to use when sorting results.", "x-component": "select", "x-options": {"uniques": {"label": "Uniques", "description": "The number of unique viewers that watched at least 1 video of a creator for at least 30s to completion"}, "quality_views": {"label": "Quality Views", "description": "The number of 30-second views watched for a minimum of 30s or to completion."}, "watchtime": {"label": "Watchtime", "description": "The aggregated number of minutes watched on views above 30s or to completion across a creator video content."}, "reach": {"label": "Reach", "description": "The percentage of unique viewers reached by a creator based on the census population for the selected geographic and demographic"}, "watchtime_per_unique": {"label": "Watchtime per Unique", "description": "the average minutes watched across a creator video content per unique viewer"}, "watchtime_per_unique_view": {"label": "Watchtime per Unique View", "description": "The average minutes watched by a unique viewer per distinct video view"}, "uniques_growth_mom": {"label": "Uniques Growth", "description": "Month over month growth on unique viewers"}, "quality_views_growth_mom": {"label": "Quality Views Growth", "description": "Month over month growth on 30-second views"}, "watchtime_growth_mom": {"label": "Watchtime Growth", "description": "Month over month growth on minutes watched"}, "watchtime_per_unique_growth_mom": {"label": "Watchtime per Unique Growth", "description": "Month over month growth on average minutes watched per unique viewer"}, "watchtime_per_unique_view_growth_mom": {"label": "Watchtime per Unique View Growth", "description": "Month over month growth on average minutes watched by a unique viewer per distinct video view"}}}, "month": {"type": "string", "x-component": "month", "description": "Specifies a month to sort results by. By default, last full month is used.", "x-months": [1, 2, 3, 4, 7, 13]}}}, "scroll": {"type": "object", "description": "Defines parameters to scroll through results.", "properties": {"id": {"type": "string", "description": "A unique id associated with the current query for which results are being retrieved. Note that the scroll token will expire if not used within 1 minute."}, "size": {"type": "integer", "description": "The maximum number of creators to include for each window of results. Subsequent requests to creator.ratings will retrieve another \"size\" results. This parameter will default to 10 if not specified. The maximum value is 100.", "x-min": 1, "x-max": 100}}}}}}}}, "responses": {"200": {"description": "A JSON array of videos", "headers": {"Tubular-RateLimit-Overall-Limit": {"description": "The overall rate limit is 60 requests per minute. This rate limit applies to any combination of API methods that are called within a trailing 1-minute timeframe.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Overall-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Limit": {"description": "The concurrency rate limit is set to 1. This means that no more than a single request can be made at a time (i.e., in parallel). Attempting to issue a video.search request while a video.facets request is still running, for example will cause the video.search request to return a rate_limited error.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Remaining": {"description": "Number of concurrent requests available for use.", "schema": {"type": "integer"}}, "Tubular-Quota-Rows-Consumed": {"description": "Number of rows consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Consumed": {"description": "Number of quota units consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Limit": {"description": "Total quota units available for the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Remaining": {"description": "Number of quota units remaining in the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Expires-After": {"description": "Date and time when the current quota period ends.", "schema": {"type": "string", "format": "date-time"}}, "Tubular-RateLimit-FacetSummary-Limit": {"description": "All aggregated request for either creators or videos are inherently expensive. Because of this, Tubular places a limit of no more than 6 total facet and summary requests per minute.", "schema": {"type": "integer"}}, "Tubular-RateLimit-FacetSummary-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"type": "object", "properties": {"ok": {"type": "boolean", "description": "Whether request was successful."}, "total": {"type": "integer", "description": "Total number of creators matching the query."}, "scroll_id": {"type": "string", "description": "Unique identifier to get the next page of results."}, "results": {"type": "array", "description": "Audience insights results.", "items": {"type": "object", "properties": {"id": {"type": "string", "description": "Creator ID the row pertains to."}, "name": {"type": "string", "description": "Creator name."}, "platform": {"type": "string", "description": "A platform the metrics are returned for."}, "month": {"type": "string", "description": "A month the metric are provided for."}, "demographics": {"type": "string", "description": "Demographic key"}, "uniques": {"type": "integer", "description": "The number of unique viewers that watched at least 1 video of a creator for at least 30s to completion"}, "quality_views": {"type": "integer", "description": "The number of 30-second views watched for a minimum of 30s or to completion."}, "watchtime": {"type": "integer", "description": "The aggregated number of minutes watched on views above 30s or to completion across a creator video content."}, "reach": {"type": "number", "format": "double", "description": "The percentage of unique viewers reached by a creator based on the census population for the selected geographic and demographic"}, "watchtime_per_unique": {"type": "number", "format": "double", "description": "the average minutes watched across a creator video content per unique viewer"}, "watchtime_per_unique_view": {"type": "number", "format": "double", "description": "The average minutes watched by a unique viewer per distinct video view"}, "uniques_growth_mom": {"type": "number", "format": "double", "description": "Month over month growth on unique viewers."}, "quality_views_growth_mom": {"type": "number", "format": "double", "description": "Month over month growth on 30-second views."}, "watchtime_growth_mom": {"type": "integer", "description": "Month over month growth on minutes watched."}, "watchtime_per_unique_growth_mom": {"type": "number", "format": "double", "description": "Month over month growth on average minutes watched per unique viewer."}, "watchtime_per_unique_view_growth_mom": {"type": "number", "format": "double", "description": "Month over month growth on average minutes watched by a unique viewer per distinct video view."}, "uniques_ratio": {"type": "number", "format": "double", "description": "The unique viewers ratio of the given demographic bucket to all demographic buckets specified. The values vary from 0 to 1 where 1 is 100%."}, "watchtime_ratio": {"type": "number", "format": "double", "description": "The watchtime ratio of the given demographic bucket to all demographic buckets specified. The values vary from 0 to 1 where 1 is 100%."}, "quality_views_ratio": {"type": "number", "format": "double", "description": "The quality views ratio of the given demographic bucket to all demographic buckets specified. The values vary from 0 to 1 where 1 is 100%."}}}}}}}}}, "429": {"description": "The query is quota or rate-limited.", "headers": {"Tubular-RateLimit-Overall-Limit": {"description": "The overall rate limit is 60 requests per minute. This rate limit applies to any combination of API methods that are called within a trailing 1-minute timeframe.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Overall-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Limit": {"description": "The concurrency rate limit is set to 1. This means that no more than a single request can be made at a time (i.e., in parallel). Attempting to issue a video.search request while a video.facets request is still running, for example will cause the video.search request to return a rate_limited error.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Remaining": {"description": "Number of concurrent requests available for use.", "schema": {"type": "integer"}}, "Tubular-Quota-Rows-Consumed": {"description": "Number of rows consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Consumed": {"description": "Number of quota units consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Limit": {"description": "Total quota units available for the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Remaining": {"description": "Number of quota units remaining in the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Expires-After": {"description": "Date and time when the current quota period ends.", "schema": {"type": "string", "format": "date-time"}}, "Tubular-RateLimit-FacetSummary-Limit": {"description": "All aggregated request for either creators or videos are inherently expensive. Because of this, Tubular places a limit of no more than 6 total facet and summary requests per minute.", "schema": {"type": "integer"}}, "Tubular-RateLimit-FacetSummary-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}}}}}}, "/property.ratings": {"x-requires": ["api_premium"], "x-group": ["data", "audience"], "post": {"summary": "Get Tubular Audience Ratings (T.A.R.) monthly metrics for one or more properties optionally segmented by demographic groups.", "parameters": [{"in": "header", "description": "Tubular API key.", "name": "Api-Key", "schema": {"type": "string"}}], "requestBody": {"content": {"application/json": {"schema": {"type": "object", "required": ["query"], "properties": {"query": {"type": "object", "description": "A JSON string representation of the property search parameters.", "properties": {"included": {"type": "object", "description": "A property filter to be included by the query. Defaults to include everything if not specified.", "properties": {"properties": {"type": "array", "x-component": "select", "description": "An array of creator property identifiers to use in the filter. Available creator properties can be obtained via a VideoFacets query. Defaults to all creator properties if not specified.", "x-autocomplete": "qb/searchProperties", "x-add": true, "items": {"type": "string"}}, "property_types": {"type": "array", "description": "An array of property types to query.", "x-component": "select", "x-options": {"brand": "Brand", "media company": "Media Company"}, "items": {"type": "string"}}, "property_countries": {"type": "array", "description": "Specifies the countries associated with properties to use in the filter (e.g., only properties associated with either the United States or France). Countries are represented as two-letter ISO 3166-1 alpha-2 codes (e.g. us, fr, gb, jp, ge). Available property countries can be obtained via a /creator.facets query. Defaults to all content countries if not specified.", "items": {"type": "string"}, "x-component": "select", "x-autocomplete": "qb/getCountries"}, "property_industries": {"type": "array", "description": "An array of property industry identifiers to use in the filter. Available property industries can be obtained via a /creator.facets query. Useful for brands. Defaults to all property industries if not specified.", "x-component": "select", "x-options": {"1": "Technology", "2": "Travel & Leisure", "3": "Music", "4": "CPG", "5": "Automotive", "6": "Financial & Insurance", "7": "Toys & Board Games", "8": "Media", "9": "Retail", "10": "Logistics & Heavy Industry", "11": "Other", "12": "Apparel & Accessories", "13": "Beverages", "14": "Personal Care & Health", "15": "Education", "16": "Public Service & Nonprofit", "17": "Food", "19": "Telecom", "20": "Pets", "21": "Sports Teams & Leagues", "22": "Gaming", "23": "Energy", "25": "Electronics", "27": "Broadcast, Cable, Radio, Film", "28": "Digital First Media", "29": "Magazine & Newspaper", "30": "Beauty"}, "items": {"type": "integer"}}}}, "excluded": {"type": "object", "description": "A property filter to be excluded by the query. Defaults to not exclude anything if not specified.", "properties": {"properties": {"type": "array", "x-component": "select", "description": "An array of creator property identifiers to use in the filter. Available creator properties can be obtained via a VideoFacets query. Defaults to all creator properties if not specified.", "x-autocomplete": "qb/searchProperties", "x-add": true, "items": {"type": "string"}}, "property_types": {"type": "array", "description": "An array of property types to query.", "x-component": "select", "x-options": {"brand": "Brand", "media company": "Media Company"}, "items": {"type": "string"}}, "property_countries": {"type": "array", "description": "Specifies the countries associated with properties to use in the filter (e.g., only properties associated with either the United States or France). Countries are represented as two-letter ISO 3166-1 alpha-2 codes (e.g. us, fr, gb, jp, ge). Available property countries can be obtained via a /creator.facets query. Defaults to all content countries if not specified.", "items": {"type": "string"}, "x-component": "select", "x-autocomplete": "qb/getCountries"}, "property_industries": {"type": "array", "description": "An array of property industry identifiers to use in the filter. Available property industries can be obtained via a /creator.facets query. Useful for brands. Defaults to all property industries if not specified.", "x-component": "select", "x-options": {"1": "Technology", "2": "Travel & Leisure", "3": "Music", "4": "CPG", "5": "Automotive", "6": "Financial & Insurance", "7": "Toys & Board Games", "8": "Media", "9": "Retail", "10": "Logistics & Heavy Industry", "11": "Other", "12": "Apparel & Accessories", "13": "Beverages", "14": "Personal Care & Health", "15": "Education", "16": "Public Service & Nonprofit", "17": "Food", "19": "Telecom", "20": "Pets", "21": "Sports Teams & Leagues", "22": "Gaming", "23": "Energy", "25": "Electronics", "27": "Broadcast, Cable, Radio, Film", "28": "Digital First Media", "29": "Magazine & Newspaper", "30": "Beauty"}, "items": {"type": "integer"}}}}}}, "filter": {"type": "object", "properties": {"platform": {"type": "string", "x-component": "select", "description": "Return metrics for the given platform. Be default cross-platforms results are returned.", "x-options": {"youtube": "YouTube", "facebook": "Facebook"}}, "audience": {"type": "object", "description": "Defines audience segments to get metrics for.", "properties": {"ages": {"type": "array", "x-component": "select", "description": "A list of age ranges to get metrics for.", "x-options": {"13_17": "13-17", "18_24": "18-24", "25_34": "25-34", "35_44": "35-44", "45_54": "45-54", "55_plus": "55+"}, "items": {"type": "string"}}, "genders": {"type": "array", "x-component": "select", "description": "A list of genders to get metrics for.", "x-options": {"f": "Females", "m": "Males"}, "items": {"type": "string"}}, "countries": {"type": "array", "x-component": "select", "description": "A list of countries to get metrics for.", "x-options": {"US": "US", "BR": "BR", "DE": "DE", "FR": "FR", "GB": "GB", "MX": "MX", "GLOBAL": "GLOBAL"}, "items": {"type": "string"}}}}, "period": {"type": "object", "description": "Months range to get metrics for. Data is available from 2020-02 to the last full month. Some countries (DE, MX, GB) have a later start date.", "properties": {"since": {"type": "string", "x-component": "month", "x-min-month": "2020-02", "description": "Min month in YYYY-MM format. Earliest available month is 2020-02."}, "until": {"type": "string", "x-component": "month", "x-min-month": "2020-02", "description": "Max month in YYYY-MM format. By default these values are set to the last full month."}}}}}, "segmentation_attributes": {"type": "array", "x-component": "select", "description": "An attribute to segment the results by.", "items": {"type": "string"}, "x-options": {"audience": {"label": "Audience", "description": "Return results segmented by audience groups set in the filter"}}}, "sort": {"type": "object", "description": "Defines how results are sorted when multiple creators are returned. Note, that sorting applies across creators so when results are segmented by demographics or multiple months are requested, results within creator segments/months are not sorted.", "properties": {"metric": {"type": "string", "description": "Metric to use when sorting results.", "x-component": "select", "x-options": {"uniques": {"label": "Uniques", "description": "The number of unique viewers that watched at least 1 video of a creator for at least 30s to completion"}, "quality_views": {"label": "Quality Views", "description": "The number of 30-second views watched for a minimum of 30s or to completion."}, "watchtime": {"label": "Watchtime", "description": "The aggregated number of minutes watched on views above 30s or to completion across a creator video content."}, "reach": {"label": "Reach", "description": "The percentage of unique viewers reached by a creator based on the census population for the selected geographic and demographic"}, "watchtime_per_unique": {"label": "Watchtime per Unique", "description": "the average minutes watched across a creator video content per unique viewer"}, "watchtime_per_unique_view": {"label": "Watchtime per Unique View", "description": "The average minutes watched by a unique viewer per distinct video view"}, "uniques_growth_mom": {"label": "Uniques Growth", "description": "Month over month growth on unique viewers"}, "quality_views_growth_mom": {"label": "Quality Views Growth", "description": "Month over month growth on 30-second views"}, "watchtime_growth_mom": {"label": "Watchtime Growth", "description": "Month over month growth on minutes watched"}, "watchtime_per_unique_growth_mom": {"label": "Watchtime per Unique Growth", "description": "Month over month growth on average minutes watched per unique viewer"}, "watchtime_per_unique_view_growth_mom": {"label": "Watchtime per Unique View Growth", "description": "Month over month growth on average minutes watched by a unique viewer per distinct video view"}}}, "month": {"type": "string", "x-component": "month", "description": "Specifies a month to sort results by. By default, last full month is used.", "x-months": [1, 2, 3, 4, 7, 13]}}}, "scroll": {"type": "object", "description": "Defines parameters to scroll through results.", "properties": {"id": {"type": "string", "description": "A unique id associated with the current query for which results are being retrieved. Note that the scroll token will expire if not used within 1 minute."}, "size": {"type": "integer", "description": "The maximum number of creators to include for each window of results. Subsequent requests to creator.ratings will retrieve another \"size\" results. This parameter will default to 10 if not specified. The maximum value is 100.", "x-min": 1, "x-max": 100}}}}}}}}, "responses": {"200": {"description": "A JSON array of videos", "headers": {"Tubular-RateLimit-Overall-Limit": {"description": "The overall rate limit is 60 requests per minute. This rate limit applies to any combination of API methods that are called within a trailing 1-minute timeframe.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Overall-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Limit": {"description": "The concurrency rate limit is set to 1. This means that no more than a single request can be made at a time (i.e., in parallel). Attempting to issue a video.search request while a video.facets request is still running, for example will cause the video.search request to return a rate_limited error.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Remaining": {"description": "Number of concurrent requests available for use.", "schema": {"type": "integer"}}, "Tubular-Quota-Rows-Consumed": {"description": "Number of rows consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Consumed": {"description": "Number of quota units consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Limit": {"description": "Total quota units available for the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Remaining": {"description": "Number of quota units remaining in the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Expires-After": {"description": "Date and time when the current quota period ends.", "schema": {"type": "string", "format": "date-time"}}, "Tubular-RateLimit-FacetSummary-Limit": {"description": "All aggregated request for either creators or videos are inherently expensive. Because of this, Tubular places a limit of no more than 6 total facet and summary requests per minute.", "schema": {"type": "integer"}}, "Tubular-RateLimit-FacetSummary-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"type": "object", "properties": {"ok": {"type": "boolean", "description": "Whether request was successful."}, "total": {"type": "integer", "description": "Total number of creators matching the query."}, "scroll_id": {"type": "string", "description": "Unique identifier to get the next page of results."}, "results": {"type": "array", "description": "Audience insights results.", "items": {"type": "object", "properties": {"id": {"type": "string", "description": "Property ID the row pertains to."}, "name": {"type": "string", "description": "Property name."}, "platform": {"type": "string", "description": "A platform the metrics are returned for."}, "month": {"type": "string", "description": "A month the metric are provided for."}, "demographics": {"type": "string", "description": "Demographic key"}, "uniques": {"type": "integer", "description": "The number of unique viewers that watched at least 1 video of a property for at least 30s to completion"}, "quality_views": {"type": "integer", "description": "The number of 30-second views watched for a minimum of 30s or to completion."}, "watchtime": {"type": "integer", "description": "The aggregated number of minutes watched on views above 30s or to completion across a property video content."}, "reach": {"type": "number", "format": "double", "description": "The percentage of unique viewers reached by a creator based on the census population for the selected geographic and demographic"}, "watchtime_per_unique": {"type": "number", "format": "double", "description": "the average minutes watched across a property video content per unique viewer"}, "watchtime_per_unique_view": {"type": "number", "format": "double", "description": "The average minutes watched by a unique viewer per distinct video view"}, "uniques_growth_mom": {"type": "number", "format": "double", "description": "Month over month growth on unique viewers."}, "quality_views_growth_mom": {"type": "number", "format": "double", "description": "Month over month growth on 30-second views."}, "watchtime_growth_mom": {"type": "integer", "description": "Month over month growth on minutes watched."}, "watchtime_per_unique_growth_mom": {"type": "number", "format": "double", "description": "Month over month growth on average minutes watched per unique viewer."}, "watchtime_per_unique_view_growth_mom": {"type": "number", "format": "double", "description": "Month over month growth on average minutes watched by a unique viewer per distinct video view."}, "uniques_ratio": {"type": "number", "format": "double", "description": "The unique viewers ratio of the given demographic bucket to all demographic buckets specified. The values vary from 0 to 1 where 1 is 100%."}, "watchtime_ratio": {"type": "number", "format": "double", "description": "The watchtime ratio of the given demographic bucket to all demographic buckets specified. The values vary from 0 to 1 where 1 is 100%."}, "quality_views_ratio": {"type": "number", "format": "double", "description": "The quality views ratio of the given demographic bucket to all demographic buckets specified. The values vary from 0 to 1 where 1 is 100%."}}}}}}}}}, "429": {"description": "The query is quota or rate-limited.", "headers": {"Tubular-RateLimit-Overall-Limit": {"description": "The overall rate limit is 60 requests per minute. This rate limit applies to any combination of API methods that are called within a trailing 1-minute timeframe.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Overall-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Limit": {"description": "The concurrency rate limit is set to 1. This means that no more than a single request can be made at a time (i.e., in parallel). Attempting to issue a video.search request while a video.facets request is still running, for example will cause the video.search request to return a rate_limited error.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Remaining": {"description": "Number of concurrent requests available for use.", "schema": {"type": "integer"}}, "Tubular-Quota-Rows-Consumed": {"description": "Number of rows consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Consumed": {"description": "Number of quota units consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Limit": {"description": "Total quota units available for the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Remaining": {"description": "Number of quota units remaining in the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Expires-After": {"description": "Date and time when the current quota period ends.", "schema": {"type": "string", "format": "date-time"}}, "Tubular-RateLimit-FacetSummary-Limit": {"description": "All aggregated request for either creators or videos are inherently expensive. Because of this, Tubular places a limit of no more than 6 total facet and summary requests per minute.", "schema": {"type": "integer"}}, "Tubular-RateLimit-FacetSummary-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}}}}}}, "/custom_list.create": {"x-requires": ["api_intelligence"], "x-group": ["asset"], "post": {"summary": "Create a new creator or video custom list containing one or more creators or video identifiers, respectively.", "parameters": [{"in": "header", "description": "Tubular API key.", "name": "Api-Key", "schema": {"type": "string"}}], "requestBody": {"content": {"application/json": {"schema": {"type": "object", "required": ["custom_list"], "properties": {"custom_list": {"type": "object", "description": "object describing a custom list details", "required": ["title", "type"], "properties": {"title": {"type": "string", "description": "The title associated with a custom list."}, "type": {"type": "string", "x-component": "select", "description": "Specifies which type of custom list the ids are associated with.", "x-options": {"creator": {"label": "Creator List", "description": "The creator_ids parameter will be included"}, "video": {"label": "Video List", "description": "The video_ids parameter will be included"}}}, "creator_ids": {"type": "array", "description": "A list of zero or more creator identifiers associated with the custom list. This parameter will only be included if the type of custom list being retrieved is a \"creator\" type and will otherwise be omitted.", "x-component": "select", "x-autocomplete": "qb/searchCreators", "x-add": true, "items": {"type": "string"}}, "video_ids": {"type": "array", "description": "A list of zero or more video identifiers associated with the custom list. This parameter will only be included if the type of custom list being retrieved is a \"video\" type and will otherwise be omitted..", "items": {"type": "object", "required": ["platform", "id"], "properties": {"platform": {"type": "string", "description": "The social platform for the video.", "x-component": "select", "x-options": {"youtube": "YouTube", "facebook": "Facebook", "instagram": "Instagram", "twitch": "Twitch", "tiktok": "TikTok"}}, "id": {"type": "string", "description": "A platform-specific unique identifier tied to the video. Typically, this identifier is also included by the social platform URL where a video can be viewed (e.g., the URL \"https://www.youtube.com/watch?v=abc123\" for video id \"abc123\" is used to refer to a YouTube video with that id)."}}}}}}}}}}}, "responses": {"200": {"description": "Status of operation", "headers": {"Tubular-RateLimit-Overall-Limit": {"description": "The overall rate limit is 60 requests per minute. This rate limit applies to any combination of API methods that are called within a trailing 1-minute timeframe.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Overall-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Limit": {"description": "The concurrency rate limit is set to 1. This means that no more than a single request can be made at a time (i.e., in parallel). Attempting to issue a video.search request while a video.facets request is still running, for example will cause the video.search request to return a rate_limited error.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Remaining": {"description": "Number of concurrent requests available for use.", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"type": "object", "properties": {"ok": {"type": "boolean", "description": "Whether request was successful."}, "id": {"type": "integer", "description": "The unique identifier associated with the custom list that was just created."}}}}}}, "429": {"description": "The query is rate-limited.", "headers": {"Tubular-RateLimit-Overall-Limit": {"description": "The overall rate limit is 60 requests per minute. This rate limit applies to any combination of API methods that are called within a trailing 1-minute timeframe.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Overall-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Limit": {"description": "The concurrency rate limit is set to 1. This means that no more than a single request can be made at a time (i.e., in parallel). Attempting to issue a video.search request while a video.facets request is still running, for example will cause the video.search request to return a rate_limited error.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Remaining": {"description": "Number of concurrent requests available for use.", "schema": {"type": "integer"}}}}}}}, "/custom_list.delete": {"x-requires": ["api_intelligence"], "x-group": ["asset"], "delete": {"summary": "Delete an existing custom list", "parameters": [{"in": "header", "description": "Tubular API key.", "name": "Api-Key", "schema": {"type": "string"}}], "requestBody": {"content": {"application/json": {"schema": {"type": "object", "required": ["id"], "properties": {"id": {"type": "integer", "description": "Specifies the identifier associated with the custom list that will be deleted."}}}}}}, "responses": {"200": {"description": "Status of operation", "headers": {"Tubular-RateLimit-Overall-Limit": {"description": "The overall rate limit is 60 requests per minute. This rate limit applies to any combination of API methods that are called within a trailing 1-minute timeframe.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Overall-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Limit": {"description": "The concurrency rate limit is set to 1. This means that no more than a single request can be made at a time (i.e., in parallel). Attempting to issue a video.search request while a video.facets request is still running, for example will cause the video.search request to return a rate_limited error.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Remaining": {"description": "Number of concurrent requests available for use.", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"type": "object", "properties": {"ok": {"type": "boolean", "description": "Whether request was successful."}}}}}}, "429": {"description": "The query is rate-limited.", "headers": {"Tubular-RateLimit-Overall-Limit": {"description": "The overall rate limit is 60 requests per minute. This rate limit applies to any combination of API methods that are called within a trailing 1-minute timeframe.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Overall-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Limit": {"description": "The concurrency rate limit is set to 1. This means that no more than a single request can be made at a time (i.e., in parallel). Attempting to issue a video.search request while a video.facets request is still running, for example will cause the video.search request to return a rate_limited error.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Remaining": {"description": "Number of concurrent requests available for use.", "schema": {"type": "integer"}}}}}}}, "/custom_list.update": {"x-requires": ["api_intelligence"], "x-group": ["asset"], "post": {"summary": "Updates an existing creator or video custom list by either adding or removing videos and/or creators.", "parameters": [{"in": "header", "description": "Tubular API key.", "name": "Api-Key", "schema": {"type": "string"}}], "requestBody": {"content": {"application/json": {"schema": {"type": "object", "required": ["custom_list_ids", "operation"], "properties": {"custom_list_ids": {"type": "array", "items": {"type": "integer"}, "x-component": "select", "x-add": true, "description": "List of custom lists to update."}, "operation": {"type": "string", "x-component": "select", "description": "Operation to perform.", "x-options": {"add": "Add", "delete": "Delete"}}, "creator_ids": {"type": "array", "description": "List of creator IDs to add or remove. This parameter should be populated only when updating creator custom lists.", "x-component": "select", "x-autocomplete": "qb/searchCreators", "x-add": true, "items": {"type": "string"}}, "video_ids": {"type": "array", "description": "List of video IDs to add or remove. This parameter should be populated only when updating video custom lists.", "items": {"type": "object", "required": ["platform", "id"], "properties": {"platform": {"type": "string", "description": "The social platform for the video.", "x-component": "select", "x-options": {"youtube": "YouTube", "facebook": "Facebook", "instagram": "Instagram", "twitch": "Twitch", "tiktok": "TikTok"}}, "id": {"type": "string", "description": "A platform-specific unique identifier tied to the video. Typically, this identifier is also included by the social platform URL where a video can be viewed (e.g., the URL \"https://www.youtube.com/watch?v=abc123\" for video id \"abc123\" is used to refer to a YouTube video with that id)."}}}}}}}}}, "responses": {"200": {"description": "Status of operation", "headers": {"Tubular-RateLimit-Overall-Limit": {"description": "The overall rate limit is 60 requests per minute. This rate limit applies to any combination of API methods that are called within a trailing 1-minute timeframe.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Overall-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Limit": {"description": "The concurrency rate limit is set to 1. This means that no more than a single request can be made at a time (i.e., in parallel). Attempting to issue a video.search request while a video.facets request is still running, for example will cause the video.search request to return a rate_limited error.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Remaining": {"description": "Number of concurrent requests available for use.", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"type": "object", "properties": {"ok": {"type": "boolean", "description": "Whether request was successful."}, "error": {"type": "string", "description": "Error message in case of failure."}}}}}}, "429": {"description": "The query is rate-limited.", "headers": {"Tubular-RateLimit-Overall-Limit": {"description": "The overall rate limit is 60 requests per minute. This rate limit applies to any combination of API methods that are called within a trailing 1-minute timeframe.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Overall-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Limit": {"description": "The concurrency rate limit is set to 1. This means that no more than a single request can be made at a time (i.e., in parallel). Attempting to issue a video.search request while a video.facets request is still running, for example will cause the video.search request to return a rate_limited error.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Remaining": {"description": "Number of concurrent requests available for use.", "schema": {"type": "integer"}}}}}}}, "/custom_list.details": {"x-requires": ["api_intelligence"], "x-group": ["asset"], "get": {"summary": "Retrieves detailed information about an existing custom list", "parameters": [{"in": "header", "description": "Tubular API key.", "name": "Api-Key", "schema": {"type": "string"}}], "requestBody": {"content": {"application/json": {"schema": {"type": "object", "required": ["id"], "properties": {"id": {"type": "integer", "description": "Specifies the identifier of the custom list to retrieve."}}}}}}, "responses": {"200": {"description": "Status of operation", "headers": {"Tubular-RateLimit-Overall-Limit": {"description": "The overall rate limit is 60 requests per minute. This rate limit applies to any combination of API methods that are called within a trailing 1-minute timeframe.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Overall-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Limit": {"description": "The concurrency rate limit is set to 1. This means that no more than a single request can be made at a time (i.e., in parallel). Attempting to issue a video.search request while a video.facets request is still running, for example will cause the video.search request to return a rate_limited error.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Remaining": {"description": "Number of concurrent requests available for use.", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"type": "object", "properties": {"ok": {"type": "boolean", "description": "Whether request was successful."}, "id": {"type": "integer", "description": "The unique identifier associated with the custom list that was just created."}, "title": {"type": "string", "description": "The title associated with a custom list."}, "type": {"type": "string", "description": "Specifies which type of custom list the ids are associated with."}, "creator_ids": {"type": "array", "description": "A list of zero or more creator identifiers associated with the custom list. This parameter will only be included if the type of custom list being retrieved is a \"creator\" type and will otherwise be omitted.", "items": {"type": "string"}}, "video_ids": {"type": "array", "description": "A list of zero or more video identifiers associated with the custom list. This parameter will only be included if the type of custom list being retrieved is a \"video\" type and will otherwise be omitted..", "items": {"type": "object", "properties": {"platform": {"type": "string", "description": "The social platform for the video."}, "id": {"type": "string", "description": "A platform-specific unique identifier tied to the video. Typically, this identifier is also included by the social platform URL where a video can be viewed (e.g., the URL \"https://www.youtube.com/watch?v=abc123\" for video id \"abc123\" is used to refer to a YouTube video with that id)."}}}}}}}}}, "429": {"description": "The query is rate-limited.", "headers": {"Tubular-RateLimit-Overall-Limit": {"description": "The overall rate limit is 60 requests per minute. This rate limit applies to any combination of API methods that are called within a trailing 1-minute timeframe.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Overall-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Limit": {"description": "The concurrency rate limit is set to 1. This means that no more than a single request can be made at a time (i.e., in parallel). Attempting to issue a video.search request while a video.facets request is still running, for example will cause the video.search request to return a rate_limited error.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Remaining": {"description": "Number of concurrent requests available for use.", "schema": {"type": "integer"}}}}}}}, "/custom_list.enumerate": {"x-requires": ["api_intelligence"], "x-group": ["asset"], "get": {"summary": "Retrieves a list of all creator or video custom lists associated with the account.", "parameters": [{"in": "header", "description": "Tubular API key.", "name": "Api-Key", "schema": {"type": "string"}}], "requestBody": {"content": {"application/json": {"schema": {"type": "object", "required": ["list_type"], "properties": {"list_type": {"type": "string", "x-component": "select", "description": "Specifies the custom list type to enumerate.", "x-options": {"creator": "Creator Lists", "video": "Video Lists"}}}}}}}, "responses": {"200": {"description": "Status of operation", "headers": {"Tubular-RateLimit-Overall-Limit": {"description": "The overall rate limit is 60 requests per minute. This rate limit applies to any combination of API methods that are called within a trailing 1-minute timeframe.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Overall-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Limit": {"description": "The concurrency rate limit is set to 1. This means that no more than a single request can be made at a time (i.e., in parallel). Attempting to issue a video.search request while a video.facets request is still running, for example will cause the video.search request to return a rate_limited error.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Remaining": {"description": "Number of concurrent requests available for use.", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"type": "object", "properties": {"ok": {"type": "boolean", "description": "Whether request was successful."}, "custom_lists": {"type": "array", "description": "A list of custom lists associated with your account.", "items": {"type": "object", "properties": {"id": {"type": "integer", "description": "The identifier for the custom list. You can use the custom_list.details method to retrieve more detailed information about a particular custom list."}, "title": {"type": "string", "description": "The title associated with a custom list."}}}}}}}}}, "429": {"description": "The query is rate-limited.", "headers": {"Tubular-RateLimit-Overall-Limit": {"description": "The overall rate limit is 60 requests per minute. This rate limit applies to any combination of API methods that are called within a trailing 1-minute timeframe.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Overall-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Limit": {"description": "The concurrency rate limit is set to 1. This means that no more than a single request can be made at a time (i.e., in parallel). Attempting to issue a video.search request while a video.facets request is still running, for example will cause the video.search request to return a rate_limited error.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Remaining": {"description": "Number of concurrent requests available for use.", "schema": {"type": "integer"}}}}}}}, "/dashboard.list": {"x-requires": ["api_dashboard"], "x-group": ["asset"], "post": {"summary": "Get a list of dashboards created within the APP.", "parameters": [{"in": "header", "description": "Tubular API key.", "name": "Api-Key", "schema": {"type": "string"}}], "requestBody": {"description": "Get a list of dashboard IDs associated with the current account", "content": {"application/json": {"schema": {}}}}, "responses": {"200": {"description": "Status of operation", "headers": {"Tubular-RateLimit-Overall-Limit": {"description": "The overall rate limit is 60 requests per minute. This rate limit applies to any combination of API methods that are called within a trailing 1-minute timeframe.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Overall-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Limit": {"description": "The concurrency rate limit is set to 1. This means that no more than a single request can be made at a time (i.e., in parallel). Attempting to issue a video.search request while a video.facets request is still running, for example will cause the video.search request to return a rate_limited error.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Remaining": {"description": "Number of concurrent requests available for use.", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"type": "object", "properties": {"ok": {"type": "boolean", "description": "Whether request was successful."}, "dashboards": {"type": "array", "description": "A list of dashboard id and name.", "items": {"type": "object", "properties": {"id": {"type": "integer", "description": "The identifier associated with the current dashboard."}, "name": {"type": "string", "description": "The caption associated with the current dashboard."}}}}}}}}}, "429": {"description": "The query is rate-limited.", "headers": {"Tubular-RateLimit-Overall-Limit": {"description": "The overall rate limit is 60 requests per minute. This rate limit applies to any combination of API methods that are called within a trailing 1-minute timeframe.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Overall-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Limit": {"description": "The concurrency rate limit is set to 1. This means that no more than a single request can be made at a time (i.e., in parallel). Attempting to issue a video.search request while a video.facets request is still running, for example will cause the video.search request to return a rate_limited error.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Remaining": {"description": "Number of concurrent requests available for use.", "schema": {"type": "integer"}}}}}}}, "/dashboard.metrics": {"x-requires": ["api_dashboard"], "x-group": ["data"], "post": {"summary": "Returns top level summary statistics for a particular track dashboard.", "parameters": [{"in": "header", "description": "Tubular API key.", "name": "Api-Key", "schema": {"type": "string"}}], "requestBody": {"content": {"application/json": {"schema": {"type": "object", "required": ["dashboard_id"], "properties": {"dashboard_id": {"type": "integer", "x-component": "select", "description": "The identifier of the requested track dashboard. Only dashboards owned by the user for whom the authenticated token was generated for will be accepted.", "x-source": "qb/getDashboards"}, "date_start": {"type": "string", "x-component": "date", "description": "A date in the format YYYY-MM-DD representing the starting date for the timeframe of data that you want back. This defaults to 90 days from today if not specified."}, "date_end": {"type": "string", "x-component": "date", "description": "A date in the format YYYY-MM-DD representing the ending date for the timeframe of data that you want back. This defaults today if not specified."}}}}}}, "responses": {"200": {"description": "Status of operation", "headers": {"Tubular-RateLimit-Overall-Limit": {"description": "The overall rate limit is 60 requests per minute. This rate limit applies to any combination of API methods that are called within a trailing 1-minute timeframe.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Overall-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Limit": {"description": "The concurrency rate limit is set to 1. This means that no more than a single request can be made at a time (i.e., in parallel). Attempting to issue a video.search request while a video.facets request is still running, for example will cause the video.search request to return a rate_limited error.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Remaining": {"description": "Number of concurrent requests available for use.", "schema": {"type": "integer"}}, "Tubular-Quota-Rows-Consumed": {"description": "Number of rows consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Consumed": {"description": "Number of quota units consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Limit": {"description": "Total quota units available for the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Remaining": {"description": "Number of quota units remaining in the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Expires-After": {"description": "Date and time when the current quota period ends.", "schema": {"type": "string", "format": "date-time"}}, "Tubular-RateLimit-FacetSummary-Limit": {"description": "All aggregated request for either creators or videos are inherently expensive. Because of this, Tubular places a limit of no more than 6 total facet and summary requests per minute.", "schema": {"type": "integer"}}, "Tubular-RateLimit-FacetSummary-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"type": "object", "properties": {"ok": {"type": "boolean", "description": "Whether request was successful."}, "metrics": {"type": "array", "description": "A list of dashboard platform metrics objects broken down by platform.", "items": {"type": "object", "properties": {"platform": {"type": "string", "description": "The platform name identifier."}, "views": {"type": "integer", "description": "The sum of the views over the time period for the current date."}, "engagements": {"type": "integer", "description": "The sum of the engagements over the time period for the current date."}, "uploads": {"type": "integer", "description": "The sum of the uploads over the time period for the current date."}}}}}}}}}, "429": {"description": "The query is rate-limited.", "headers": {"Tubular-RateLimit-Overall-Limit": {"description": "The overall rate limit is 60 requests per minute. This rate limit applies to any combination of API methods that are called within a trailing 1-minute timeframe.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Overall-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Limit": {"description": "The concurrency rate limit is set to 1. This means that no more than a single request can be made at a time (i.e., in parallel). Attempting to issue a video.search request while a video.facets request is still running, for example will cause the video.search request to return a rate_limited error.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Remaining": {"description": "Number of concurrent requests available for use.", "schema": {"type": "integer"}}, "Tubular-Quota-Rows-Consumed": {"description": "Number of rows consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Consumed": {"description": "Number of quota units consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Limit": {"description": "Total quota units available for the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Remaining": {"description": "Number of quota units remaining in the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Expires-After": {"description": "Date and time when the current quota period ends.", "schema": {"type": "string", "format": "date-time"}}, "Tubular-RateLimit-FacetSummary-Limit": {"description": "All aggregated request for either creators or videos are inherently expensive. Because of this, Tubular places a limit of no more than 6 total facet and summary requests per minute.", "schema": {"type": "integer"}}, "Tubular-RateLimit-FacetSummary-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}}}}}}, "/dashboard.trends": {"x-requires": ["api_dashboard"], "x-group": ["data"], "post": {"summary": "Get historical daily views, engagements and uploads for a particular track dashboard.", "parameters": [{"in": "header", "description": "Tubular API key.", "name": "Api-Key", "schema": {"type": "string"}}], "requestBody": {"content": {"application/json": {"schema": {"type": "object", "required": ["dashboard_id"], "properties": {"dashboard_id": {"type": "integer", "x-component": "select", "x-source": "qb/getDashboards", "x-add": true, "description": "The identifier of the requested track dashboard. Only dashboards owned by the user for whom the authenticated token was generated for will be accepted."}, "date_start": {"type": "string", "format": "date", "description": "A date in the format YYYY-MM-DD representing the starting date for the timeframe of data that you want back. This defaults to 90 days from today if not specified."}, "date_end": {"type": "string", "format": "date", "description": "A date in the format YYYY-MM-DD representing the ending date for the timeframe of data that you want back. This defaults today if not specified."}}}}}}, "responses": {"200": {"description": "Status of operation", "headers": {"Tubular-RateLimit-Overall-Limit": {"description": "The overall rate limit is 60 requests per minute. This rate limit applies to any combination of API methods that are called within a trailing 1-minute timeframe.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Overall-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Limit": {"description": "The concurrency rate limit is set to 1. This means that no more than a single request can be made at a time (i.e., in parallel). Attempting to issue a video.search request while a video.facets request is still running, for example will cause the video.search request to return a rate_limited error.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Remaining": {"description": "Number of concurrent requests available for use.", "schema": {"type": "integer"}}, "Tubular-Quota-Rows-Consumed": {"description": "Number of rows consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Consumed": {"description": "Number of quota units consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Limit": {"description": "Total quota units available for the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Remaining": {"description": "Number of quota units remaining in the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Expires-After": {"description": "Date and time when the current quota period ends.", "schema": {"type": "string", "format": "date-time"}}, "Tubular-RateLimit-FacetSummary-Limit": {"description": "All aggregated request for either creators or videos are inherently expensive. Because of this, Tubular places a limit of no more than 6 total facet and summary requests per minute.", "schema": {"type": "integer"}}, "Tubular-RateLimit-FacetSummary-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"type": "object", "properties": {"ok": {"type": "boolean", "description": "Whether request was successful."}, "trends": {"type": "array", "description": "A list of dashboard platform trends objects broken down by platform.", "items": {"type": "object", "properties": {"platform": {"type": "string", "description": "The platform name identifier."}, "trends": {"type": "array", "items": {"type": "object", "properties": {"day": {"type": "string", "description": "A date in the format YYYY-MM-DD corresponding to the current trends."}, "views": {"type": "integer", "description": "The sum of the views over the time period for the current date."}, "engagements": {"type": "integer", "description": "The sum of the engagements over the time period for the current date."}, "uploads": {"type": "integer", "description": "The sum of the uploads over the time period for the current date."}}}}}}}}}}}}, "429": {"description": "The query is rate-limited.", "headers": {"Tubular-RateLimit-Overall-Limit": {"description": "The overall rate limit is 60 requests per minute. This rate limit applies to any combination of API methods that are called within a trailing 1-minute timeframe.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Overall-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Limit": {"description": "The concurrency rate limit is set to 1. This means that no more than a single request can be made at a time (i.e., in parallel). Attempting to issue a video.search request while a video.facets request is still running, for example will cause the video.search request to return a rate_limited error.", "schema": {"type": "integer"}}, "Tubular-RateLimit-Concurrency-Remaining": {"description": "Number of concurrent requests available for use.", "schema": {"type": "integer"}}, "Tubular-Quota-Rows-Consumed": {"description": "Number of rows consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Consumed": {"description": "Number of quota units consumed by the query.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Limit": {"description": "Total quota units available for the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Remaining": {"description": "Number of quota units remaining in the current quota period.", "schema": {"type": "integer"}}, "Tubular-Quota-Units-Expires-After": {"description": "Date and time when the current quota period ends.", "schema": {"type": "string", "format": "date-time"}}, "Tubular-RateLimit-FacetSummary-Limit": {"description": "All aggregated request for either creators or videos are inherently expensive. Because of this, Tubular places a limit of no more than 6 total facet and summary requests per minute.", "schema": {"type": "integer"}}, "Tubular-RateLimit-FacetSummary-Remaining": {"description": "Number of API requests remaining before the rate limit is hit.", "schema": {"type": "integer"}}}}}}}}}