---
title: "Get Video"
method: GET
path: "/live/{platform}/videos/{platformVideoId}"
tags: ["Live Data"]
---

# Get Video

`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`

Fetches one video with its current counts.

| Platform | `platformVideoId` | Notes |
| --- | --- | --- |
| TikTok | numeric video id | |
| Instagram | the shortcode in the Reel's URL | Reels only; a photo post or carousel is refused |
| YouTube | the 11-character video id | built for Shorts |
| Facebook | numeric reel or video id | the share count is rounded above 999 |
| Snapchat | the Spotlight snap id | likes 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.

## Path parameters

- `platform` 'facebook' | 'instagram' | 'tiktok' | 'youtube' | 'snapchat', required: Social media platform (facebook, instagram, tiktok, youtube, snapchat)
- `platformVideoId` string, required: Native platform video id found in the URL of the video

## Query parameters

- `region` string, nullable: Region code (2-letter ISO country code)

## Response `200`

OK

- object
  - `platform` 'facebook' | 'instagram' | 'tiktok' | 'youtube' | 'snapchat', required: Social media platform (facebook, instagram, tiktok, youtube, snapchat)
  - `platform_video_id` string, nullable, required: Native platform video id found in the URL of the video
  - `platform_account_id` string, nullable, required: Native platform account id
  - `account_username` string, nullable, required
  - `account_display_name` string, nullable, required
  - `account_profile_picture_url` string, nullable: URL
  - `region` string, nullable: Region code (2-letter ISO country code)
  - `caption` string, nullable, required
  - `hashtags` string[]
  - `content_type` 'video' | 'slideshow', nullable, required: Filter by content types (video, slideshow)
  - `video_index` integer, nullable, required
  - `thumbnail_url` string, nullable: URL
  - `download_url` string, nullable: URL
  - `music_id` string, nullable, required
  - `music_title` string, nullable, required
  - `music_artist` string, nullable, required
  - `music_album` string, nullable, required
  - `music_play_url` string, nullable: URL
  - `image_urls` string[]
  - `music_cover_url` string, nullable: URL
  - `is_original_music` boolean, nullable, required
  - `duration_seconds` number, nullable, required
  - `view_count` integer, nullable, required
  - `like_count` integer, nullable, required
  - `comment_count` integer, nullable, required
  - `share_count` integer, nullable, required
  - `bookmark_count` integer, nullable, required
  - `engagement_rate` number, nullable, required
  - `published_at` string, date-time, nullable, required

## Other responses

- `400`: 400
- `401`: 401
- `402`: 402
- `403`: 403
- `404`: 404
- `408`: 408
- `429`: 429
- `500`: 500
- `502`: 502

---

[API](https://skmtc.dev/viral/apis/viral-app-api.md) · [All operations](https://skmtc.dev/viral/apis/viral-app-api/llms.txt) · [OpenAPI document](https://skmtc.dev/viral/apis/viral-app-api/revisions/31e97fa79ef1?raw)