Live Data

Search Videos

Searches videos on a platform by keyword.

query and pageToken work the same on every platform. region and language are hints: applied where a platform's search supports them and ignored elsewhere. The filters of a search route (sortBy, dateRange, accountType) change which results come back, so a platform that cannot apply one refuses the request with a validation error instead of ignoring it.

Platform	Finds	Pages	Applies	Counts in a result
TikTok	videos	paged	region, sortBy, dateRange	views, likes, comments, shares, saves
Instagram	Reels	paged		views, likes, comments, shares, saves
YouTube	Shorts	paged	region, language, dateRange	views
Facebook	videos and reels	paged		views, rounded for some searches
Snapchat	Spotlight videos	one page of up to 24		views, likes, comments, shares

dateRange has one set of values. A platform supports the periods its own filter has and refuses the others:

dateRange	TikTok	YouTube	Instagram, Facebook, Snapchat
hour	refused	yes	refused
day	yes (the last 24 hours)	yes (today)	refused
week	yes	yes	refused
month	yes	yes	refused
3-months, 6-months	yes	refused	refused
year	refused	yes	refused
all-time	yes	yes	refused

Examples:

GET /live/tiktok/search/videos?query=ugc&sortBy=likes&dateRange=week&region=US
GET /live/youtube/search/videos?query=ugc&dateRange=month&language=en
GET /live/instagram/search/videos?query=ugc
GET /live/snapchat/search/videos?query=fitness
GET /live/youtube/search/videos?query=ugc&dateRange=6-months is refused with 400: "dateRange "6-months" is not supported for YouTube. Supported: hour, day, week, month, year, all-time."
GET /live/instagram/search/videos?query=ugc&sortBy=likes is refused with 400: "sortBy is supported for TikTok only."

A YouTube result without dateRange has an id, title, thumbnail and a rounded view count; with dateRange it also has the channel, the exact view count, the day of publishing and the length. A Facebook result's publish date is exact to the day, or null where Facebook shows only an age. Snapchat results that mention none of the query's words are left out. A pageToken on a platform that has one page returns an empty page and is not charged.

Optional live endpoint. You do not need this endpoint for normal API integrations; prefer tracked accounts, tracked videos, analytics, projects, and Creator Hub endpoints when working with viral.app data.

⚠️ Consumes extra credits: 3 credits per request. Additional charges may apply.

Headers:

X-Viral-Credits-Consumed
X-Viral-Credits-Meter
X-Viral-Credits-Benefited-Remaining
X-Viral-Credits-Can-Purchase-Extra
Retry-After (on 429 responses)

A page past the only one of a one-page lookup costs nothing: it carries X-Viral-Credits-Consumed: 0 and X-Viral-Credits-Meter, without the two balance headers.

get/live/{platform}/search/videos

Request

Base URL: https://viral.app/api/v1
URL: https://viral.app/api/v1/live/{platform}/search/videos
Auth: API key in header x-api-key

Path parameters

platform'facebook' | 'instagram' | 'tiktok' | 'youtube' | 'snapchat' required

Social media platform (facebook, instagram, tiktok, youtube, snapchat)

Example:facebook

Query parameters

querystring required

Search query string

Example:nike

pageTokenstring nullable

Opaque cursor token used to fetch the next page

Example:v2:eyJvZmZzZXQiOjIwLCJsaW1pdCI6MjB9

regionstring nullable

Region code (2-letter ISO country code)

Example:US

languagestring nullable

Language code for localized search results (BCP 47 style)

Example:en

sortBy'relevance' | 'date' | 'likes' nullable

TikTok only: order of the results, relevance (the default), date or likes. Refused on other platforms.

Example:likes

Only videos published within this period: hour, day, week, month, 3-months, 6-months, year or all-time. TikTok supports day, week, month, 3-months, 6-months and all-time; YouTube supports hour, day, week, month, year and all-time. A period a platform does not support is refused, and so is any value on Instagram, Facebook and Snapchat. The older names today, yesterday, this-week, this-month, last-3-months and last-6-months are still accepted.

Example:week

Response

nextPageTokenstring nullable required

Example response

{
  "videos": [
    {
      "platform": "facebook",
      "platform_video_id": "7123456789012345678",
      "platform_account_id": "7123456789012345678",
      "account_profile_picture_url": "https://www.myproject.com",
      "region": "US",
      "hashtags": [
        "brand"
      ],
      "thumbnail_url": "https://www.myproject.com",
      "download_url": "https://www.myproject.com",
      "music_play_url": "https://www.myproject.com",
      "image_urls": [
        "https://www.myproject.com"
      ],
      "music_cover_url": "https://www.myproject.com"
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.