Live Data

Get Video

Fetches one video with its current counts.

PlatformplatformVideoIdNotes
TikToknumeric video id
Instagramthe shortcode in the Reel's URLReels only; a photo post or carousel is refused
YouTubethe 11-character video idbuilt for Shorts
Facebooknumeric reel or video idthe share count is rounded above 999
Snapchatthe Spotlight snap idlikes are Spotlight boosts

Examples:

  • GET /live/tiktok/videos/7123456789012345678
  • GET /live/instagram/videos/Dd6pJEpAkQ5
  • GET /live/youtube/videos/dQw4w9WgXcQ

Fields a platform does not publish are null. region is a hint: TikTok uses it as the country the lookup is made from, the other platforms ignore it.

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}/videos/{platformVideoId}

Request

  • Base URL: https://viral.app/api/v1
  • URL: https://viral.app/api/v1/live/{platform}/videos/{platformVideoId}
  • 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
platformVideoIdstring required

Native platform video id found in the URL of the video

Example:7123456789012345678

Query parameters

regionstring nullable

Region code (2-letter ISO country code)

Example:US

Response

OK

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

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

platform_video_idstring nullable required

Native platform video id found in the URL of the video

platform_account_idstring nullable required

Native platform account id

account_usernamestring nullable required
account_display_namestring nullable required
account_profile_picture_urlstring nullable

URL

regionstring nullable

Region code (2-letter ISO country code)

captionstring nullable required
hashtagsstring[]
content_type'video' | 'slideshow' nullable required

Filter by content types (video, slideshow)

video_indexinteger nullable required
thumbnail_urlstring nullable

URL

download_urlstring nullable

URL

music_idstring nullable required
music_titlestring nullable required
music_artiststring nullable required
music_albumstring nullable required
music_play_urlstring nullable

URL

image_urlsstring[]
music_cover_urlstring nullable

URL

is_original_musicboolean nullable required
duration_secondsnumber nullable required
view_countinteger nullable required
like_countinteger nullable required
comment_countinteger nullable required
share_countinteger nullable required
bookmark_countinteger nullable required
engagement_ratenumber nullable required
published_atstring date-time nullable required

Example response

{
  "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.